Additional
Harness runtime routes and authority boundaries
Synced from github.com/CoWork-OS/CoWork-OS/docs
P01 implementation inventory, inspected at a84735698560df421c32d7669f31efe9a4e23fee on 27 September 2026. This is a source and executable-test map, not a claim that every route has passed live acceptance. P02, P03 and P08a are separate changes; their guarantees must be validated at their own commit.
Shared native execution path
Root tasks enter through AgentDaemon.createTask() or a caller that persists a task and invokes AgentDaemon.startTask(). startTask() queues execution; startTaskImmediate() applies the effective workspace/access configuration and creates a TaskExecutor. Follow-ups and resumed tasks also have executor entrypoints and must retain the same restrictions.
- State: AgentDaemon, task repositories, SessionRuntime and turn kernel. Task/TaskEvent persistence remains authoritative during the current dual-write rollout. In
emitTimelineEvent, failures projecting events into work-session protocol/contracts are explicitly non-blocking. The existing work-session stores are the extension point, not evidence of a completed authority migration. - Policy: task creation normalization, daemon permission evaluation/approval fingerprinting, ToolPolicyPipeline and PermissionEngine. Named profiles, legacy ceilings, role restrictions, workspace policy and administrative denials must be distinguished. A parent being full-authority does not establish a child's role-specific authority.
- Tool dispatch: the executor owns scheduling and ToolExecutionCoordinator; ToolRegistry owns native handlers and the policy-wrapped invocation boundary. Some executor helper paths call the registry directly, so scheduler coverage must not be inferred from registry coverage.
- Usage: executor cumulative usage and
checkBudgets()apply per task, alongside guardrails. They are not a task-tree reservation system. Auxiliary models, delegated tasks and remote runtimes need separate accounting qualification before a total-cost guarantee. - Terminal state: executor finalizers and daemon completion/cancellation write native task state/events;
VerificationRuntimegates eligible tasks. WorkSessionContractService currently projects aggregate completion into requirement satisfaction. Task completion is not independent proof of every requirement.
Route inventory
“Partial tests” means executable coverage exists for the named boundary with mocks or component fixtures; it does not mean a full deployed flow has been exercised. “Missing” names the precise acceptance test still needed. Native rows inherit the five authorities above unless an exception is stated.
| Route | Production entry and dispatch | Authority/terminal differences | Existing executable contract and remaining gap |
|---|---|---|---|
| Desktop task creation | IPC handlers, TASK_CREATE → task persistence → startTask; multi-agent/collaborative branches may fan out | IPC validation and effective profile precede the native kernel. Renderer reconciliation is presentation state. | Partial: task-entrypoint normalization, renderer reconciliation, executor entrypoints. Missing: real IPC create → permitted/denied tool → durable terminal/evidence under the same profile. |
| Direct CLI, attached and detached | CLI main, runTask → direct child process → direct-run, main → createTask/startTask | Normal local runs do not use remote Control Plane. Electron app-entry launch is preferred when available; Node fallback exists. CLI ownership heartbeat, signal and detached-run state are additional lifecycle authorities. | Partial: CLI main, direct runtime launch, direct-run lifecycle. Missing: isolated real CLI run with tool effect, interruption and profile parity across Electron/Node. |
| Node daemon / remote CLI / coworkctl | Node main → Node Control Plane methods, TASK_CREATE → task repository → startTask | task.create requires admin scope and normalizes named profiles/legacy shell ceilings. cowork run --remote and coworkctl are clients, not separate kernels. | Partial: protocol/server, Node method sanitization, common normalization, and real Node smoke for socket authentication, creation and missing-provider failure. Missing: successful real tool policy → effect → terminal contract. Input-response tests alone do not cover task creation. |
| Desktop Control Plane / Electron headless daemon | Electron main → Control Plane handlers, TASK_CREATE → startTask; coworkd launches the same Electron main | Separate registration implementation from Node; do not assume parity. Transport authorization is additional to task/tool authority. | Partial: task-event transport, event bridge, common normalization. Missing: paired desktop/Node task-create policy/terminal acceptance. |
| Gateway conversations and isolated side work | gateway router creates or follows up native tasks; gateway ingress also uses hook-style ingress | Channel authentication/session ownership, role/restriction selection, delivery and bot approval policy surround the kernel. A channel delivery receipt is not task/artifact proof. | Partial: router specialization, follow-up persistence, bot recovery. Missing: authenticated channel → actual denied/allowed tool → delivered verified result with real service read-back. |
| Scheduled runs, Electron and Node | CronService, run → injected createTask; implementations in Electron main and Node main | Cron owns job/run leases, polling result and delivery outbox; native task owns execution. Electron adds council/briefing branches and scheduled-job/source metadata; Node wiring is not identical. | Partial: cron service, cron budget profile, cron outcomes. Missing: both production dependency wirings with a real task and deadline/cancellation/effect receipt. |
| Native delegation and live graph | spawn_agent/orchestrate_agents in registry → OrchestrationGraphEngine → daemon createChildTask | Graph nodes/handles own dependency and child linkage; native children also have task rows. Parent/child restrictions intersect; budgets are currently per executor. | Partial: child task inheritance, agent messaging. Missing: dedicated live-graph real-SQLite dispatch/crash/restart and mixed local/remote parent cancellation tests (P05). |
| Verifier and internal read-only helper | VerificationRuntime → daemon runReadOnlyChildTaskAndWait → createChildTask; helper callers share the native child path | Verifier/explicit readOnlyExecution forces plan mode, disables shell and removes external runtime. Ordinary researcher role does not get that same hard boundary at this baseline; P08a repairs it. | Partial: verification runtime, worker roles, child inheritance tests. Missing at baseline: actual role-by-tool mutation rejection under a bypass parent, including indirect writes (P08a). |
| Outbound remote ACP graph node | Live graph dispatchNode → remote ACP invoker | Remote service owns its tool execution/usage. Local graph stores remote task ID/status; it cannot inherit native ToolRegistry enforcement by assertion. Dispatch precedes persistence of remote ID. | Partial: ACP handler exercises remote cancellation with mocks. Missing: real remote dispatch/receipt loss/reconciliation and root cancellation reaching remote descendants. |
| External CLI engine through acpx | Executor external-runtime branch → AcpxRuntimeRunner | External engine owns tools; native tool pipeline is not its enforcement boundary. assertAcpxExecutionAuthority refuses bounded access profiles. Events/changed-path claims are normalized locally; declared output checks remain necessary. | Partial: AcpxRuntimeRunner, ACP prompt outcomes. Missing: pinned installed-engine acceptance for effect/usage/cancel across each supported engine. Mock NDJSON does not prove external enforcement. |
| Inbound ACP task request | ACP handler, acp.task.create → injected local createTask or remote invoker | ACP requester/operator authorization and its persisted task mapping surround local/remote execution. Only the local branch eventually shares native policy. | Partial: ACP handler tests cover registration, task creation, ownership filters, cancellation and persisted reload. Missing: actual transport/local-daemon/remote-service composite acceptance. |
| Hooks and event triggers | AgentIngressService, createTaskFromAgentAction → daemon createTask; EventTriggerService dispatches configured actions | Hook auth/mapping/session dedupe precedes task creation. Session-key collision can create then cancel a duplicate native task; it is not an exactly-once external-effect guarantee. | Partial: hook server, hook sessions, event triggers. Missing: live ingress → native effect with profile/endpoint ownership and cancellation; P03 must not confuse fixture-server success with this proof. |
| Routines, heartbeat and strategic dispatch | routines, HeartbeatDispatchEngine, StrategicPlannerService → injected/native createTask | Each owns a run/intent lifecycle around the native task. Routine deterministic workflow actions can also execute outside a model turn via action executor; those effects need their own policy/evidence checks. | Partial: routine service, workflow executor, heartbeat, planner. Missing: cross-surface run/receipt/cancel acceptance against actual effects. |
| Managed sessions and product helper creators | ManagedSessionService → startTask; DocumentEditorSessionService, ComparisonService, SubconsciousLoopService, DiscordSupervisorService, tray and Electron main helpers create/start native tasks | Additional session, draft, supervisor or automation ownership must not replace tool authority. Child/helper classification must be checked per caller; “helper” in a name does not imply read-only enforcement. | Partial: managed sessions, document session, subconscious loop. Missing: creator-by-creator live permission/effect/terminal parity; comparison/tray/supervisor are explicitly unqualified here. |
Dormant DAG disposition
The legacy SubAgentOrchestrator has no production constructor/import caller found in the inspected source. The legacy OrchestrationRepository is imported by that class, its tests, and an unused registry import; this is not a live dispatch call. Production instantiates OrchestrationGraphEngine in the daemon and uses it from registry delegation tools.
Decision: keep the legacy class quarantined from new production use. Do not repair/adopt it as part of P02/P03/P08a or replace the live graph to address its defects. Removal can be a separate compatibility cleanup after checking stored legacy data and external imports. Any proposed adoption requires real-SQLite concurrent-update, failed-dependency and restart tests; its existing mock-based tests are insufficient. This inventory is a maintenance decision, not a new runtime block on imports.
Validation and follow-through
The initial P01 check ran 14 existing contract suites with 245 passing tests, covering entrypoint normalization, direct-runtime launch/lifecycle, gateway specialization, cron, inbound/external ACP, verifier/native-child inheritance, routines, heartbeat, strategic planning and managed sessions. They are component tests with the boundaries shown above.
For a reproducible native entrypoint smoke check, run:
npm run build:daemon
node scripts/qa/smoke_native_entrypoint.cjs
The script starts the compiled Node daemon with a fresh temporary profile/workspace and a minimal environment containing no provider credentials. It checks rejection before authentication, creates a workspace and task through the real WebSocket API, verifies the expected missing-provider failure is persisted without widening shellAccess: false, and stops its owned process. It saves a redacted log and JSON receipt in the reported temporary directory. It does not invoke a model, establish successful tool execution, or validate desktop/remote-engine routes. Missing compiled output or native SQLite support is a prerequisite failure; the script does not install or rebuild dependencies.
Existing tests referenced above establish only their stated boundaries. For each implementation PR record the exact base/head, failing-before reproduction, focused check commands, environment, real entrypoint exercised, and unverified routes. Use isolated profiles/workspaces and fake credentials/services for deterministic adversarial checks. Do not run fixtures against a human's default database or auto-approve unspecified requests.
P01 is complete when every route family has source, state/policy/tool/usage/terminal ownership, an existing or explicitly missing contract test, and the dormant/live graph distinction. It does not require pretending the listed missing acceptance suites already exist. P02 owns file integrity; P03 owns truthful isolated evaluation; P08a owns the researcher/helper boundary. Later P05/P06/P07/P09 work owns graph recovery, requirement-specific proof, effect reconciliation and shared budgets.
To refresh this inventory after routing changes, search createTask( and startTask( across src, trace callers instead of counting symbols, inspect native versus remote tool execution, and update the named coverage gaps. A passing common-kernel suite alone cannot certify each registration/transport path.