Local and network agent coordinator

Implemented October 26–27, 2026; live acceptance remains open. Canonical scope: reports/specs/agent-coordinator-20261026/spec.md at repository root. GitCafe epic #14 / workstreams #15–20. This document describes implemented limits, not a claim that all release gates passed.

Use it

Open Assistant → Connections → Agents. Discover this device, select an executable/workspace, or inspect an exact A2A agent-card/execution origin or Tincan profile/peer. Discovery never installs or logs in. An inspection is valid for ten minutes and must match the saved configuration. Directory rows separate installed/configured capability evidence from actual task status.

Assistant → Jobs offers a structured job builder. Select exact agents, approved operations, workspace, dependencies and a grant deadline (maximum two hours). Review the complete plan, then Run plan. Ask the assistant to inspect registered agents and draft a job through rs_agents; it cannot approve or dispatch. Independent tasks run up to four at once, one per peer and one local writer. Dependencies use bounded attributed summaries/manifests, not automatic file transfer.

Stop answer stops generated chat text. Cancel task/job persists an execution stop request; only a matching provider confirmation marks cancelled. Unsupported stop becomes Unknown. Stop gameplay belongs to Command and is separate. Changing/disabling a connection does not reroute or stop already-dispatched work.

Results preserve each peer's statements and receipts. A tool-free Codex supervisor uses gpt-6.1-sol/high to synthesize bounded immutable evidence with exact task citations. Its separate durable result revision survives refresh; failed/interrupted synthesis is retried explicitly without repeating any agent task. Rebuild results does not rerun tasks. Inline artifact/result events are stored as hashed JSON evidence; remote artifact URLs remain references and are not fetched automatically. Export downloads local evidence. Remote statements that tests passed are not tests run by this app. Continue and Retry create new reviewable jobs/task IDs; they do not replay uncertain work.

Architecture and files

• server/coordinator/client.ts: observer-side bounded IPC queue; no agent/model work on world-feed loop.
• worker.ts, owner.ts: one child process, atomic PID/start/boot/generation lock, two-second heartbeat. No takeover from stale heartbeat alone.
• store.ts, permissions.ts, shared/coordinator.ts: authoritative SQLite journal, revisions, frozen routing, grants, DAG, operation approvals, dedupe, leases and retention.
• scheduler.ts: admission, dependency projection, deadlines, provider events/status, 30-second cancellation confirmation. Never resubmits an unknown attempt.
• workflow.ts: long-lived Mastra instance and file-backed LibSQL validate → dispatch → suspend/wait → collect workflow. Journal controls external effects. Failed snapshots are surfaced for recovery; they are not blindly restarted.
• adapters/: Codex app-server, Mastra ACP, direct A2A lifecycle/SSE and Tincan. See COORDINATOR-ADAPTERS.md for actual capabilities.
• routes.ts: same local operator session/CSRF as Command; reads are {data:...}. Assistant/MCP expose read/draft, not approval.
• artifacts.ts, redaction.ts: bounded owned evidence, reservation/hash checks, credential redaction and tombstones.
• src/coordinator/: Frosted directory, reviewed drafts, Jobs, permission/input requests, results. Legacy Connections planning handoff remains accessible.

Data is under data/coordinator/: coordinator.sqlite, mastra.db, owner.lock, artifacts/, confinement/. Only the worker opens these stores for writing. Legacy link/handoff rows are copied once from intel.sqlite; originals stay intact and imported peers require reinspection. Do not create a second worker, delete a live lock, attach unrelated provider sessions, or wipe unknown tasks to bypass leases.

Terminal detail is summarized before pruning after 90 days; summary history expires after one year. Active/unknown work remains retained. Terminal, unreferenced artifact bytes expire after 90 days only after the durable job summary is saved; earlier manual removal preserves a provenance tombstone. Limits: 20 MiB/artifact, 200 MiB/job, 2 GiB total reservations plus stored artifacts.

Localhost and credentials

The app listens only on localhost. Outbound registered A2A/Tincan connections may reach the network. No Funnel, inbound remote dashboard, automatic Tailscale join, gameplay login or repository upload is added.

A2A URLs reject userinfo/query/fragments, redirects, metadata and forbidden address families. DNS resolution is validated and pinned to the actual request socket. Exact card/execution origins are reviewed on inspection; new execution origins need another inspection. Private HTTP must resolve exclusively to private addresses.

Optional A2A bearer credential references are server-side: RS_COORDINATOR_CREDENTIAL_REFS lists allowed environment-variable names; RS_COORDINATOR_CREDENTIAL_BINDINGS maps each reference to {name,origin}. The origin must match exactly. UI displays reference names/configured booleans only; never paste secret bytes into the dashboard or a job. Native local-profile credential registration is not implemented.

Current limits and unfinished acceptance

Codex can research and, after actual confinement checks, use app-mediated read/list/write tools with exact per-write approval. On certified macOS devices, run_tests runs 1–16 explicit Bun test files with a read-only workspace, private scratch writes, no subprocesses and no network. Each run requires operator approval. Inspection proves denial of outside/credential access, traversal, symlinks, shell/install/background processes and egress, plus confirmed cancellation; runtime or sandbox binary changes invalidate that proof. Tests requiring writes to the workspace, network or subprocesses will fail. There is no unconfined fallback. Arbitrary shell, installs, network tools and gameplay are disabled. ACP currently supports research with explicit deny-default permissions; its general local subprocess does not yet satisfy scoped-code confinement. A2A/Tincan peers currently support research; remote code-scope attestation is not yet implemented. Do not label these limits as full coding-harness parity.

Real release pilots still require operator-selected Codex/ACP scratch workspace and two network peers, including one actual A2A task and provider-confirmed cancellation. Fixture passing proves protocol handling, not account availability. Browser QA and performance evidence live under reports/palantir-validation/agent-coordinator-20261026/ at repo root. No real gameplay account was connected for this feature.

Commands

From apps/rs-palantir: pnpm run check, bun test server/coordinator src/coordinator, bun scripts/coordinator.ts status, bun scripts/coordinator.ts agents, bun scripts/coordinator.ts draft /absolute/plan.json. MCP tools: agent_directory, agent_jobs, agent_job, agent_job_draft through bun scripts/mcp.ts. Approval stays in the UI. OpenAPI starts at /api/openapi.json.

Provider changes must retain negative path/symlink/credential/network tests, original provider question IDs, task/session/attempt identity, unknown-after-send recovery, and the distinction between stopping text and stopping work. Use GitCafe/registered origin for collaboration; do not publish this repository through GitHub.