@engineeros/connector 1.25.2 → 1.28.1

package/README.md

@@ -1,384 +1,386 @@
-# EngineerOS Connector
-
-The connector uses an authenticated EngineerOS WebSocket for pairing, workspace identity, run lifecycle, and evidence. Coding work can run through any agent in the official ACP registry, a custom ACP v1-compatible command over stdio, or the Forge command line. Direct Codex CLI remains available as the compatibility path.
-
-## Independent Goal runner
-
-Connector 1.2.0 hands Goal jobs to a separate local runner. Closing the connector terminal or losing its WebSocket does not stop an executing Goal. Progress and final results use HTTP; undelivered results remain on disk for retry. Windows supervisors and workers use a windowless launcher; Goal runs and agent commands do not open new terminals.
-
-Install from a permanent global installation or repository checkout, then run:
-
-```text
-engineeros-connector runner install --workspace D:\Puli\work\workspaces\caresched
-engineeros-connector runner status --workspace D:\Puli\work\workspaces\caresched
-```
-
-The first Goal dispatch also installs/starts the runner when using a permanent executable path. Temporary `npx` cache paths cannot host a persistent service: install the connector globally first. Update the backend for the HTTP claim endpoint before dispatching Goals.
-
-Windows uses Task Scheduler under your current user, restarts after failure, and resumes saved jobs at sign-in following reboot. Linux uses a systemd user service; enable user lingering separately if recovery must start before login. Existing running jobs stay with their current process; resume an interrupted run to hand it to the new service.
-
-Files under your project's `.engineeros` directory:
-
-- `runner/inbox/`: durable job dispatch requests.
-- `runner/service.json`: supervisor PID and heartbeat.
-- `runner/service.log`: supervisor startup and cleanup diagnostics.
-- `runs/<run-id>/job.json`: execution/delivery status, saved assignment, pending result or failure.
-- `runs/<run-id>/state.json`: coding session and implementation/verification checkpoints.
-- `runs/<run-id>/activity.log`: timestamped activity and periodic inactivity status.
-- `runs/<run-id>/worker.log`: worker console diagnostics.
-
-The runner stops and records a resumable failure after ten minutes without agent events, except when explicitly waiting for user input. Restore missing prerequisites or agent usage before using **Resume run**. Acceptance and integration remain controlled by EngineerOS.
-
-There is no wall-clock execution cutoff. Runs stop after at most two repair-and-review cycles following the initial review. The inactivity safeguard above still stops a silent agent; waiting for your answer does not consume a repair cycle. Successful results awaiting upload are not executed again.
-
-### Delete a Goal and its sandboxes
-
-Choose **Delete Goal** in the Goal detail header and confirm. This deletes all revisions, runs, receipts, proof results, attachments and run questions for that Goal. Connected runners first stop every run in the revision family, then remove owned isolated Git worktrees (including uncommitted sandbox files), checkpoints, queued dispatches and logs. The source repository, its local changes, Git branches and unrelated worktrees are preserved. External registered worktrees require their matching saved checkpoints to establish ownership. Manually managed external environments remain the external runner's responsibility.
-
-Deletion remains visible as **Deleting** until every assigned connector acknowledges cleanup. The supervisor polls authenticated cleanup requests every 15 seconds, including while the connector terminal is closed. Offline machines and lost acknowledgements retry safely. Cleanup errors are displayed on the Goal with **Retry cleanup**; a live worker lock or ambiguous sandbox ownership prevents removal. Active backend verification must finish before deletion starts. Small markers in `runner/deleted-runs/` prevent delayed dispatches from restarting deleted work.
-
-After updating an existing installation, reinstall the runner task with `runner install` and restart the existing supervisor to load the new code. The Windows scheduled action must use `wscript.exe` and `runner/launch.vbs`. Logs remain in the project's `.engineeros` directory; no terminal is needed for a run.
-
-If the Windows runner task was disabled, `engineeros-connector runner start --workspace PATH` explicitly enables it and starts processing queued jobs. Incoming dispatches remain queued while the task is disabled and print this recovery command; they do not enable it automatically. Do not resend the Goal just to start its queued job.
-
-
-## Connect an official ACP agent
-
-Connector 0.33.0 supports **Deliver capability**. EngineerOS immediately queues the capability as a Goal request;
-it does not generate or require approval of a separate implementation slice first. The coding agent reads the
-frozen local design, writes its implementation plan inside the run worktree, then implements, tests and repairs
-the work. Independent testing and review agents verify the delivered commit. Required user choices use the
-existing run questions and resume the same work. The final handover includes the committed plan, source changes,
-test evidence and review results. Integration still requires the user's review.
-
-Planning and verification read the assigned design from its local Git commit, so later design synchronization
-does not silently change a running delivery. The implementation plan is stored at
-`docs/delivery/<goal-id>/implementation-plan.md` and remains part of the delivered repository history.
-
-EngineerOS reads the curated [ACP agent registry](https://agentclientprotocol.com/registry), caches it for 24 hours, and uses the registry's pinned distribution for the current platform. The catalog includes Codex, Claude, Gemini, GitHub Copilot, Goose, OpenCode, Qwen Code, Cursor, and other compatible agents as they are published. List the current catalog, prepare the selected agent, then pair the workspace:
-
-```sh
-npx --yes @engineeros/connector@latest agents
-npx --yes @engineeros/connector@latest agent gemini install
-npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard --agent gemini
-```
-
-Registry `npx` and `uvx` packages are prepared with their native package runner. Registry binaries are downloaded into `~/.engineeros/agents`, checked against the published SHA-256 digest when present, and launched from that managed location. The connector checks the selected distribution before pairing. Agent processes stay alive while the connector is active, project conversations reuse their ACP sessions, and response chunks reach Copilot as the agent produces them.
-
-## Pair an ACP coding agent
-
-Run the command from the repository the agent should work in:
-
-```powershell
-npx --yes @engineeros/connector@latest pair PAIRING-CODE --url http://localhost:8000 --workspace . --onboard --agent-name "My ACP agent" --agent-command my-agent --agent-args '["--acp"]'
-```
-
-`--agent-command` must start an ACP v1 agent over NDJSON stdio. `--agent-args` is a JSON array so arguments are passed without invoking a shell. Omit `--agent` and the custom command options to use the installed Codex CLI directly.
-
-Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.
-
-## Pair Forge
-
-[Forge](https://forgecode.dev) is driven through its own command line rather than ACP. Install it, sign in to a provider, then pair the workspace:
-
-```sh
-forge provider login
-npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard --agent-protocol forge
-```
-
-Forge runs its own agents, so `--agent` and `--agent-command` are rejected for this protocol. The connector selects the Forge agent that carries the access an assignment is entitled to: `sage` for read-only research, planning, assessment, and verification work, and `forge` for the writable implementation phase of a registered Goal. Pairing stops with the corrective command when Forge is missing, unauthenticated, or no longer provides both agents.
-
-Each EngineerOS session maps onto a Forge conversation, so project prompts and multi-stage assessments resume with their history intact. Token usage is reported per turn, measured as the growth of the conversation while the turn ran.
-
-Every model Forge offers through the providers you are signed in to is published to EngineerOS, named with its provider because the same model is offered by more than one, along with every reasoning effort Forge accepts. Forge takes the provider, model and reasoning effort of a run from the environment of its process, so the choice made in EngineerOS applies to that run alone: it does not change the model set with `forge config set model`, and it does not disturb a run beside it. The model and effort configured in Forge are marked as the default. Pairing stops when Forge offers no models, which means no provider is signed in: run `forge provider login`, then restart the connector.
-
-The connector registers the EngineerOS project artifact tools with Forge for the current user, which is the only scope Forge trusts without a person approving a file in the workspace, so nothing is written into the repository being worked on. Forge shares that one registration across every workspace and discovers the tools once, so the run each tool acts on is carried in the environment of the Forge process rather than in the registration. Concurrent runs stay separate, and a tool called outside an EngineerOS run is refused with the reason.
-
-## Agent roles and skills
-
-The selected ACP, Forge, or Codex agent is the execution engine. EngineerOS chooses a provider-neutral role for each activity and the connector injects exactly one bundled skill:
-
-- `research` uses `project-research` to answer questions from observed project evidence.
-- `assessment` uses the internal `assessment-maintenance` skill to inspect source without changing it and edit only the assigned assessment Markdown document.
-- `planning` remains read-only and uses one server-selected skill: `product-discovery`, `experience-design`, `solution-design`, `requirements-and-acceptance`, or `delivery-planning`. Product discovery covers both intent discovery and capability shaping; delivery planning covers accepted greenfield slices and brownfield changes.
-- `implementation` uses `implementation` with workspace-write access only for a registered Goal.
-- `verification` uses `independent-verification` with read-only access for artifact review and independent Goal proof.
-
-This is intentionally a small executable catalog. Skills for hypothetical release, quality, or agent-workflow phases are not advertised until EngineerOS has a workflow that can invoke them. Harness-wide access, evidence, clarification, and output rules remain outside skill bodies, so an assignment pays only for the specialized judgment it needs. Direct Codex runs also disable ambient skill instructions; ACP providers receive the selected EngineerOS skill in the assignment prompt rather than the rest of the catalog.
-
-The connector rejects a role whose access does not match the assignment before starting the agent. Role-specific sessions preserve useful context without mixing planning, research, implementation, or verification responsibilities. A shared interaction contract makes the Agent infer the current project situation, lead with the useful outcome, and suggest one concrete next activity only when it genuinely helps. User-visible responses refer neutrally to the Agent; provider and harness details remain operational metadata.
-
-## Onboard a workspace
-
-Create a connection command from **Project steering -> Connect workspace**, then run it inside the local folder:
-
-```sh
-npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard
-```
-
-The connector uploads a bounded ZIP snapshot for a safe file inventory, then stays online for deep assessments, rescans, and Goal Runs. Inventory never executes repository code. It excludes known secrets, dependency directories, build output, compiled binaries, files larger than 5 MB, agent-tool caches, Git metadata, and connector state before upload.
-
-From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select any combination of fifteen brownfield assessment domains, collectively covering 133 internal checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Reports include only material conclusions and actions; routine healthy checklist rows are not published. Capability entries state what they own, what they link to, and what they depend on. Connector `0.17.0` starts assessments with three parallel workers and accepts the run's UI-selected limit from three through eight for every coding-agent provider. It keeps one local assessment area at `.engineeros/assessment`: `assessment.md` is the canonical document, `sections/` holds the independently editable stage documents, `.work/` is the resumable transaction area, and an accepted update adds only a concise derived entry under `changes/`. A new run seeds each stage from its durable document, and a reconnect preserves any partially edited `.work` copy, so the coding agent updates affected content instead of regenerating the assessment. ACP agents such as OpenCode use isolated stage sessions within one persistent coding-agent process. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; report content is no longer streamed over the WebSocket or written into backend assessment JSON. The backend validates stage checkpoints so dependency fan-out remains authoritative, while the connector retains completed reports and reloads interrupted ACP or Codex sessions after reconnect when the coding agent supports session restoration. Transient ACP, app-server, provider-availability, and rate-limit failures receive two bounded attempts to continue the saved session without repeating completed inspection. A changed Git commit edits the same durable assessment, retains the prior commit in assessment history, and updates published artifacts in place. Connector reports and session checkpoints are tagged with their target commit so an earlier revision cannot leak into the update. If no assessment exists, EngineerOS creates the initial assessment identity and documents. Capability detail and project-specific compliance controls fan out after their catalogs. Final synthesis reads the connector-local Markdown files, then one completed bundle is revalidated, persisted, published as canonical artifacts, and archived locally. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. The connector prints each worker's safe activity and elapsed time every 30 seconds, stops a worker that produces no agent activity for ten minutes instead of waiting indefinitely, and asks the same agent session to repair the same document when structure or backend validation fails. Assessment cannot modify tracked workspace source outside its assigned document.
-
-Every backend `422` content-validation response is returned to the stage agent with the exact failed item. Distinct validation failures continue through correction and resubmission until the complete stage is accepted. Three repetitions of the same unresolved validation error stop the automatic loop while preserving the latest local report for retry. Authentication, cancellation, source drift, and transport failures remain operational errors rather than agent-correction prompts.
-
-If Codex reports that its refresh token was already used, stop every connector process using Codex before reauthenticating. Run `codex logout`, then `codex login` in a normal terminal, and restart one connector with `start --workspace ...`. The existing EngineerOS workspace pairing remains valid. The connector stops the failed ACP runtime and reports these recovery steps without exposing its internal stack trace.
-
-Assessment runs start by reporting whether an accepted assessment exists and how stale it is. Every assigned stage still runs against the current repository revision; durable reports do not contain a trustworthy dependency manifest, so the connector never presents an old section as newly inspected. Connector-owned files under `.engineeros` are ignored before drafts or context packs are created and therefore do not pollute repository change scans.
-
-After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
-
-Capability implementation planning uses committed local context in connector `0.32.0`. The synchronized
-`INDEX.md` links to the design, product intent, preparation context, decision revisions, implementation plans,
-current Facts and normalized Sources. A planning assignment carries the task, new guidance, record references
-and the expected snapshot revision; it does not resend those artifact bodies or an assignment-specific evidence
-copy. Before starting the agent, the connector checks the revision, saves the snapshot in local Git and supplies
-a `git show` pointer to that commit. All linked records are read from the same commit, so background sync does
-not change a running plan's input. The backend rechecks the context before saving a generated plan; stale input
-or invalid output leaves the accepted plan intact. No remote push is performed.
-
-Other greenfield generation prompts receive a bounded project-evidence manifest. EngineerOS normalizes uploaded text,
-PDF, DOCX, CSV, workbook, presentation, and image Sources, and the connector materializes normalized Markdown
-and available original attachments under an assignment-specific directory in `.engineeros/context/inputs/`.
-These files are connector-owned, ignored project
-context; the active coding agent reads them as untrusted evidence through ordinary file access. Only the most
-relevant Sources are included in each assignment. Normalized text is capped at one million characters and
-original attachments at 10 MB across the assignment so the WebSocket payload stays bounded; image, workbook,
-and presentation originals receive priority because their normalized text is only a descriptor. The connector
-removes the assignment directory after the Agent finishes.
-
-When material evidence or a user decision is missing, a generation Agent can return structured clarification
-questions instead of an artifact. EngineerOS stores and presents those questions, accepts free-text or newly
-uploaded evidence, and supplies answered clarifications when the same phase is retried. The connector does not
-hold a process or WebSocket request open while waiting for a user.
-
-The complete-product greenfield path performs that question review before each generation stage. After the user
-confirms the answers, connector `0.25.0` validates the Agent's complete structured Markdown bundle and atomically
-stores its files under `.engineeros/design/01-discovery` through `.engineeros/design/06-delivery`. Every stage has
-a manifest and remains directly editable by a human. Later stages read the approved earlier directories as their
-authoritative inputs. The planning Agent remains read-only: the connector, not the Agent process, owns the bounded
-local write, and an existing stage directory must be deleted explicitly before regeneration.
-
-Project prompts use resumable, role- and purpose-specific agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the role, purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.
-
-An empty or document-only folder establishes a greenfield baseline. A code-bearing folder is assessed as brownfield. Use **Rescan** in Steering after the local workspace changes.
-
-## Reconnect
-
-Connector 1.0.0 requires the updated EngineerOS backend. Upgrade both together, then restart the existing
-connector with `start`; its saved pairing remains valid. The WebSocket carries dispatch and control messages.
-Goal progress, assessment worker status, prompt output, failure reports and results use authenticated HTTP.
-There is no application JSON ping/pong. WebSocket protocol keepalive detects connection loss; quiet Goal work
-sends an HTTP heartbeat after 15 seconds without a progress update. Idle connectors need no application heartbeat.
-
-HTTP progress keeps one request in flight and retains the latest unsent state. Prompt deltas are ordered and
-bounded; a failed progress stream does not discard the final completed response. Requests have timeouts and
-bounded retries. Goal execution attempts and sequence numbers protect against delayed updates.
-
-Run the backend as **one worker and one replica**: dispatch sockets and pending prompt waiters currently live
-in process memory. The production image now uses one worker. Multiple backend workers require a shared dispatch
-broker before enabling them. An incompatible backend or connector fails with an upgrade instruction.
-
-```sh
-npx --yes @engineeros/connector@latest start --workspace .
-```
-
-Credentials are stored per workspace under `~/.engineeros/connectors` with owner-only permissions where supported.
-If a new pairing command is accidentally run from the same folder against the same EngineerOS server, the connector reuses this saved identity instead of creating another baseline assessment.
-
-## Self-check
-
-Connector 1.12.0 checks itself and reports the result to EngineerOS, so a local problem is visible in **Project steering -> Connect workspace** instead of only in this terminal. The checks cover the Node runtime, the saved pairing, whether the EngineerOS backend answers from this machine, whether the coding agent starts, the tool registry, and stuck local Goal jobs.
-
-The report is sent when the connector connects, every five minutes while it is idle, and once more when a startup problem is about to stop it, which is the case EngineerOS could not see before: the workspace simply appeared offline. Run the same checks locally at any time, paired or not:
-
-```sh
-npx --yes @engineeros/connector@latest doctor --workspace .
-```
-
-The command prints every check with its reason and remedy, sends the report when the workspace is paired, and exits non-zero when a check failed.
-
-## Local Git history
-
-Pairing or starting connector 0.31.0 initializes a local Git repository when the project has none and creates its initial commit from source files and durable design/assessment artifacts. An empty project also gets a usable baseline. Existing repositories and their pending source changes are preserved. Git must be installed; no remote is created and nothing is pushed.
-
-As design context syncs, the connector commits new, changed and deleted durable artifact files locally. These explicit artifact paths are included even though connector runtime state is ignored. Source generated by a capability is committed by the existing implementation and verification workflow on its capability branch. Environment secrets, credentials, dependency/build directories, context indexes and temporary handover files remain excluded. Identical snapshots produce no extra commits, and artifact sync waits while an implementation run is active.
-
-## Run Goals
-
-From capability delivery, choose **Implement capability** and an online coding connector. EngineerOS prepares any missing implementation plan from the saved design, validates its prerequisites, and starts the run. **Preview plan** is optional; the detailed plan remains available without becoming a separate mandatory document review.
-
-The connector coordinates implementation, independent testing and independent code review. Native implementation subagents may work on independent tasks when the selected coding harness supports them. Testing and review run as separate read-only processes after the implementation is committed. At most two repair-and-review cycles follow the initial review; completed allowances survive resume. Repository finalization has its own single recovery attempt. Unresolved findings are then handed back with failed evidence instead of starting another repair. The handover includes the implementation report, exact revision, changed files and final check reports; persistent failures remain failed.
-
-Reuse existing shared foundations. A necessary out-of-scope prerequisite requires a recorded approval through `engineeros_request_input` with `decision_area: scope_expansion`, a stable question key, the precise addition and its reason and impact. Each run permits at most two expansion requests, including rejected or dismissed requests. Select **Approve scope expansion** in EngineerOS to authorize that specific addition; other answers do not authorize work. These approvals reach the implementer, independent reviewers and final handover. They do not reset the repair allowance or rewrite the original frozen Goal. Further expansion requires a separate Goal.
-
-When a consequential choice is missing, the implementation agent calls `engineeros_request_input` and finishes its turn. Answer the question in the active run using a suggestion or your own words. The connector keeps heartbeats active, preserves the workspace and resumes with the saved answer. Dismissal and cancellation never count as answers. Cancellation stops all workers in the run. This feature requires the updated backend and connector; it does not deploy the product or automatically approve its handover.
-
-Keep the connector online to receive Goals assigned from EngineerOS. Each run explicitly selects one workspace
-mode. `local_branch` creates or reuses the capability branch in the connected repository, runs with its exact
-local dependencies and properties, and returns to the original branch after a clean committed run. It is the
-default for a dedicated agent machine. Work left uncommitted on the current branch, staged or untracked, is
-stashed before the Goal branch is created and reapplied when the repository is handed back, so it never blocks
-a Goal and never becomes part of it. Ignored files are left in place. Work that no longer applies cleanly stays
-in `git stash list` with its recovery command reported on the run.
-`isolated_worktree` creates one durable worktree at `<project>/.engineeros/goals/<goal-id>` and reuses it
-across retries. The worktree shares Git configuration and hooks and copies individual ignored local configuration
-files; ignored dependency and build directories are not duplicated. The coding-agent process inherits the
-connector environment in both modes. Cancellation stops the agent. The connector returns changed paths, a bounded
-diff, and the exact repository ZIP; a human still performs independent attestation. Accepted work fast-forwards
-into an unchanged clean connected branch, or cherry-picks the complete Goal commit range onto a clean branch that
-advanced, then refreshes the workspace snapshot. Dirty or conflicting workspaces are never overwritten: the Goal
-branch remains available for explicit review and merge.
-
-During the writable implementation phase, Codex receives an authenticated EngineerOS MCP server automatically. It can list, read, create, update, reclassify, soft-delete, and materialize project artifacts into canonical Product records through the same repository boundary used by Copilot. The backend accepts those calls only while the assigned Goal is running. Read-only project prompts and the independent verification phase do not receive mutation tools.
-
-### Resume a failed or interrupted Goal run
-
-Connector 0.34.0 keeps new isolated Goal worktrees inside the project at `.engineeros/goals/<goal-id>`.
-Execution checkpoints live at `.engineeros/runs/<run-id>`. Start the connector with its existing pairing,
-open the Goal's run panel and select **Resume run**. A disconnected running run becomes resumable after
-90 seconds without a heartbeat. Offline resume requests wait for the assigned connector to reconnect.
-
-Resume preserves the run ID, frozen assignment, branch, files and completed implementation. It restores the
-agent session when supported and reruns interrupted verification. A completed result is retained for another
-upload attempt; changing the code causes it to be verified again. Existing worktrees are reused through Git's
-registry, so an upgrade does not move your current work. A missing workspace or corrupt checkpoint must be
-restored before resuming. Submitted results and final acceptance receipts retain their existing review flow.
-
-## Local context engine
-
-The connector keeps a local index for each workspace under `~/.engineeros/context/<connector id>/workspaces/`: file classifications, symbols, document headings, and import relationships for every safe file. Separating indexes by resolved workspace keeps the source checkout and concurrent Goal worktrees from replacing one another. An index is built at onboarding, refreshed incrementally from file digests when EngineerOS triggers a workspace refresh, and re-checked before every assignment.
-
-Every assignment prompt arrives with a bounded, task-ranked Markdown working set. It names the most relevant paths, symbol and heading locations, local dependencies, direct consumers, and candidate tests, followed by a pointer to the durable source map at `.engineeros/context/source-map.md`. The connector ranks from the assignment's focused context query, frozen Goal packet, assessment stage identity, or current project request as appropriate. It never pastes source-file contents into the prompt; the Agent reads deeper through the source map, the listed files, assessment sections, ordinary file tools, or the attached `engineeros_*` MCP tools. Ranking is structural and lexical, using indexed paths, symbols, summaries, and imports; it does not generate or store embeddings.
-
-Context preparation is a launch prerequisite for every role. The connector refreshes the correct workspace index, verifies that the source map exists, and stops before starting an agent with an actionable error when pairing identity, indexing, or map generation is unavailable. Resumed project sessions also receive a bounded `Session Memory` digest of relevant earlier turns in the same session, kept under `~/.engineeros/context/<connector id>/sessions/`, so follow-up prompts build on prior conclusions instead of re-deriving them. Entries carry a derived kind (fix, decision, change, or conclusion), and cross-session recall is stamped with its source session and last-active time.
-
-Every direct Codex assignment — project prompt, assessment, Goal implementation, and independent verification — receives the local read-only context MCP server with `engineeros_search`, `engineeros_outline`, `engineeros_read_symbol`, `engineeros_similar`, `engineeros_blast_radius`, and `engineeros_recall`. Registry-backed ACP adapters receive the same runtime-workspace server through `session/new` and `session/load`. Only a writable Goal implementation receives the authenticated EngineerOS artifact MCP server; project prompts, assessments, and verification never receive mutation tools. Custom ACP commands receive no injected servers because they have no registry MCP contract.
-
-After Goal implementation commits its isolated worktree change, the connector rebuilds context from that exact post-commit workspace before starting the independent verifier. Verification therefore receives the current task-ranked working set plus a bounded `Change Impact` section naming changed files, direct importers, and candidate tests rather than relying on the pre-change index. `engineeros_similar` helps the Agent extend existing functions, classes, and types instead of duplicating them. Stored symbol outlines omit literal constant values, MCP search responses are capped at one hundred files, and the index, source map, prompt context, and session memory remain on the local computer.
-
-## Local design artifacts
-
-Connector 0.28.0 synchronizes persisted design records into
-`.engineeros/design/projects/<project-id>/`, with `INDEX.md` linking the named
-Markdown artifacts and their current review status. Sync runs on connection,
-every ten seconds, and before project prompts and Goal execution. Goal worktrees
-receive their own copy. Assignments point the agent to the index explicitly.
-
-The database remains authoritative. Confirm edits through EngineerOS Copilot;
-local changes are overwritten by the next successful sync. Renames and deletions
-remove outdated Markdown files from this managed directory. An offline connector
-refreshes when it reconnects. The backend must provide the matching design-context
-endpoint; sync failures are reported and block new agent tasks from using stale context.
-
-## Autonomous work scan
-
-Connector 1.23.0 can tell EngineerOS what this workspace should deliver next. It scans only when the
-autonomy policy for the project asks it to: EngineerOS answers each five-minute self-check with whether
-it wants a scan, and an autonomy policy that is off, out of budget or already running a Goal never
-causes one. Turn it on, and off again, in **Project steering -> Autonomy**.
-
-When a scan is requested, the connector waits until nothing else is running here — no assessment stage,
-no prompt, no local Goal job — and then reads evidence that is already on disk: the synced design index,
-the local assessment, and Goal runs that stopped. One read-only agent turn ranks that evidence and names
-at most five capabilities worth starting, each with its reason. The turn has no write, command or tool
-access, and the scan repeats at most every thirty minutes.
-
-The connector never starts work of its own. Candidates are reported as evidence; EngineerOS re-validates
-every one against its own records, applies the policy, budget and concurrency limits, and decides whether
-to dispatch a Goal. A candidate naming a capability EngineerOS never published to this workspace is
-discarded before it is sent. A failing scan backs off like other maintenance and names itself in the
-self-check.
-
-Each report comes back with what EngineerOS turned down. The next scan asks for different work and drops
-a refused candidate even if the agent repeats it. When neither the workspace nor those refusals have
-changed, the shortlist is repeated from memory and no agent turn is spent at all, so an idle workspace
-costs nothing to keep watching.
-
-## Run spend ceiling
-
-Repair cycles bound how often work is retried, and a run that goes quiet is stopped after ten minutes.
-Neither bounds a run that keeps producing output while spending, which matters once EngineerOS starts
-Goals without anyone watching. Every delivery run therefore stops at **5,000,000 tokens**, counted across
-resumes from the saved run checkpoint and stated to the agent in its execution rules.
-
-Reaching the ceiling is a stopping point, not a crash: the committed changes and unresolved findings are
-handed over for review exactly as they are when the repair budget runs out, and the spend already made is
-reported to EngineerOS. Set `ENGINEEROS_RUN_TOKEN_CEILING` to a different whole number of tokens to raise
-or lower it for this machine.
-
-## Requirements
-
-Node.js 22 or newer, Git, and an authenticated agent. `npx` distributions use npm, `uvx` distributions require uv, and binary archives require `tar` (`unzip` for ZIP files on Linux). Registry agents report their own authentication prerequisites when they start.
-
-## Execution profiles
-
-EngineerOS can set a workspace default model and reasoning effort, then override either value for an individual Goal. The same workspace default is used for assessments, Copilot, and generated artifacts. The connector passes the resolved values to Codex CLI and reports unsupported profiles instead of silently ignoring them.
-
-Codex connectors advertise `gpt-5.6-sol` and `gpt-5.6-terra` by default. Override the choices shown in EngineerOS before starting the connector:
-
-```sh
-ENGINEEROS_AGENT_MODELS="model-a,model-b" npx @engineeros/connector start --workspace .
-```
-
-## Codex CLI compatibility
-
-The connector prints the exact Codex CLI version it will use before connecting. If the
-configured model requires a newer CLI, update Codex and restart the connector:
-
-```sh
-npm install -g @openai/codex@latest
-codex --version
-npx @engineeros/connector start --workspace .
-```
-
-## Supervisor recovery
-
-The workspace runner monitors worker health separately from progress reporting. Continuous reporting failures pause coding after one minute; missing worker health is detected after ninety seconds. Recovery preserves the sandbox and checkpoint. It allows one restart per failure category and at most two per run, with a cooldown and storage check before restarting.
-
-Unknown runtime failures may use one read-only LLM diagnosis per run through the configured agent, with a two-minute deadline. Known filesystem and network faults do not call an LLM. Diagnosis recommends retrying the checkpoint or a manual fix; it does not execute generated commands or modify the connector. Repeated failures stop automatic recovery. Inspect `runner status` and `.engineeros/runner/recovery/<run-id>.json`, fix the reported cause, then explicitly resume the existing run. Recovery budgets are retained.
-
-Verification results are cached per commit and role. Completed checks are reused. An interrupted check requires inspection before a new revision; it is not automatically billed again. Existing workers must load the new connector code before these protections apply.
-
-## Optional tool and plugin inventory
-
-Connector 1.7 advertises a curated candidate catalog alongside the operator-managed inventory. The catalog covers code intelligence, design, work management, source control, documentation, research, API development, browser testing, quality and security, data, infrastructure, observability and development environments. Candidate entries are metadata only: they are not installed, authenticated, admitted, started or exposed to coding agents.
-
-The catalog includes CodeGraph, Serena, JetBrains IDE MCP, ast-grep, Figma, Storybook, Miro, Lucid, Linear, monday.com, Atlassian Rovo, YouTrack, Notion, Slack, GitHub, GitLab, Context7, Postman, Exa, Tavily, Firecrawl, Perplexity, Playwright, Chrome DevTools, BrowserStack, Semgrep, SonarQube, Snyk, Gitleaks, Trivy, PostgreSQL MCP, Supabase, Terraform, AWS, Azure, Cloudflare, Vercel, Sentry, Grafana, Datadog, PagerDuty, Renovate, Dev Container CLI and Docker MCP Gateway. Each entry records its category, selection group, activation condition, eligible workflow profiles, provenance and default policy. Overlapping selection groups are alternatives, not permission to load every provider.
-
-Inspect the catalog and locally registered providers without starting software:
-
-```sh
-engineeros-connector tools list --workspace PATH
-engineeros-connector tools register /absolute/path/manifest.json --workspace PATH
-engineeros-connector tools disable PROVIDER_ID --workspace PATH
-engineeros-connector tools disable all --workspace PATH
-engineeros-connector tools enable PROVIDER_ID --workspace PATH
-engineeros-connector tools remove PROVIDER_ID --workspace PATH
-engineeros-connector tools sign-in PROVIDER_ID --workspace PATH
-engineeros-connector tools auth-status PROVIDER_ID --workspace PATH
-engineeros-connector tools sign-out PROVIDER_ID --workspace PATH
-```
-
-After pairing connector 1.8 or newer, open **Project → Steering → Local workspace → Tools and plugins** to search the catalog and control registered providers. The web UI can enable, disable and remove registrations through the authenticated connector session. Enabling and removal require confirmation. Registration remains local because its evaluated manifest contains machine paths and integrity metadata that are never advertised to EngineerOS.
-
-Use `enable all` to clear the global disable. Registration never installs packages or executes a provider. Replacing a pin requires explicit removal and registration. Registry files live beside the user-owned connector configuration as `<workspace-key>.tools.json`, outside the repository. The connected workspace displays their inventory, refreshed through authenticated heartbeats. Stop any abandoned operator update before removing its `.tools.json.lock` file.
-
-Manifests are strict internal JSON configuration with these required fields:
-
-| Field | Required value |
-| --- | --- |
-| `id`, `name`, `provider`, `capability_class` | Stable lowercase ID, display labels and `tool`, `skill` or `agent`. |
-| `source`, `version`, `license` | Credential-free HTTPS source, exact semantic version and license. No `latest` or version range. |
-| `launch` | For `stdio` or skill `file`: `transport`, absolute `entrypoint`, absolute `package_json` and lowercase `sha256` of the entrypoint. For `https`: `transport` and credential-free `endpoint`. No commands, arguments or environment values are accepted. |
-| `platforms` | Array containing supported `win32`, `linux` and/or `darwin`. |
-| `permissions` | `workspace` (`none`, `read`, `write`), `process` boolean, `network` HTTPS URL array, `browser` (`none`, `isolated`), `secrets` reference-name array and `external_mutations` boolean. These record requests, not runtime grants. |
-| `authentication` | `none`, operator-owned `external` instructions, or `oauth` with exact scopes and either dynamic client registration or a provider-issued public client ID. Secret values are never accepted in a manifest. Older manifests without this field remain loadable but report setup required for HTTPS or secret-bearing providers. |
-| `profiles` | Array of `discovery`, `research`, `implementation`, `verification`, `handover`. |
-| `tasks`, `exclusions` | Arrays of lowercase task IDs; at least one eligible task. |
-| `tools` | Array of objects with `name` (`provider-id:operation_name`), concise `description`, and `response_mode` (`summary` or `reference`). |
-| `policy` | `approval_required: true`, `timeout_ms` from 100 to 30000, `retry_limit` 0 or 1. Reserved for bounded provider adapters; inspection executes nothing. |
-| `evidence` | `metadata-only`. |
-| `evaluation` | `status` (`experimental` or `standard`) and a real evidence `reference`. Standard status requires completed comparative evaluation. |
-
+# EngineerOS Connector
+
+The connector uses an authenticated EngineerOS WebSocket for pairing, workspace identity, run lifecycle, and evidence. Coding work can run through any agent in the official ACP registry, a custom ACP v1-compatible command over stdio, or the Forge command line. Direct Codex CLI remains available as the compatibility path.
+
+## Independent Goal runner
+
+Connector 1.2.0 hands Goal jobs to a separate local runner. Closing the connector terminal or losing its WebSocket does not stop an executing Goal. Progress and final results use HTTP; undelivered results remain on disk for retry. Windows supervisors and workers use a windowless launcher; Goal runs and agent commands do not open new terminals.
+
+Install from a permanent global installation or repository checkout, then run:
+
+```text
+engineeros-connector runner install --workspace D:\Puli\work\workspaces\caresched
+engineeros-connector runner status --workspace D:\Puli\work\workspaces\caresched
+```
+
+The first Goal dispatch also installs/starts the runner when using a permanent executable path. Temporary `npx` cache paths cannot host a persistent service: install the connector globally first. Update the backend for the HTTP claim endpoint before dispatching Goals.
+
+Windows uses Task Scheduler under your current user, restarts after failure, and resumes saved jobs at sign-in following reboot. Linux uses a systemd user service; enable user lingering separately if recovery must start before login. Existing running jobs stay with their current process; resume an interrupted run to hand it to the new service.
+
+Files under your project's `.engineeros` directory:
+
+- `runner/inbox/`: durable job dispatch requests.
+- `runner/service.json`: supervisor PID and heartbeat.
+- `runner/service.log`: supervisor startup and cleanup diagnostics.
+- `runs/<run-id>/job.json`: execution/delivery status, saved assignment, pending result or failure.
+- `runs/<run-id>/state.json`: coding session and implementation/verification checkpoints.
+- `runs/<run-id>/activity.log`: timestamped activity and periodic inactivity status.
+- `runs/<run-id>/worker.log`: worker console diagnostics.
+
+The runner stops and records a resumable failure after ten minutes without agent events, except when explicitly waiting for user input. Restore missing prerequisites or agent usage before using **Resume run**. Acceptance and integration remain controlled by EngineerOS.
+
+There is no wall-clock execution cutoff. Runs stop after at most two repair-and-review cycles following the initial review. The inactivity safeguard above still stops a silent agent; waiting for your answer does not consume a repair cycle. Successful results awaiting upload are not executed again.
+
+### Delete a Goal and its sandboxes
+
+Choose **Delete Goal** in the Goal detail header and confirm. This deletes all revisions, runs, receipts, proof results, attachments and run questions for that Goal. Connected runners first stop every run in the revision family, then remove owned isolated Git worktrees (including uncommitted sandbox files), checkpoints, queued dispatches and logs. The source repository, its local changes, Git branches and unrelated worktrees are preserved. External registered worktrees require their matching saved checkpoints to establish ownership. Manually managed external environments remain the external runner's responsibility.
+
+Deletion remains visible as **Deleting** until every assigned connector acknowledges cleanup. The supervisor polls authenticated cleanup requests every 15 seconds, including while the connector terminal is closed. Offline machines and lost acknowledgements retry safely. Cleanup errors are displayed on the Goal with **Retry cleanup**; a live worker lock or ambiguous sandbox ownership prevents removal. Active backend verification must finish before deletion starts. Small markers in `runner/deleted-runs/` prevent delayed dispatches from restarting deleted work.
+
+After updating an existing installation, reinstall the runner task with `runner install` and restart the existing supervisor to load the new code. The Windows scheduled action must use `wscript.exe` and `runner/launch.vbs`. Logs remain in the project's `.engineeros` directory; no terminal is needed for a run.
+
+If the Windows runner task was disabled, `engineeros-connector runner start --workspace PATH` explicitly enables it and starts processing queued jobs. Incoming dispatches remain queued while the task is disabled and print this recovery command; they do not enable it automatically. Do not resend the Goal just to start its queued job.
+
+
+## Connect an official ACP agent
+
+Connector 0.33.0 supports **Deliver capability**. EngineerOS immediately queues the capability as a Goal request;
+it does not generate or require approval of a separate implementation slice first. The coding agent reads the
+frozen local design, writes its implementation plan inside the run worktree, then implements, tests and repairs
+the work. Independent testing and review agents verify the delivered commit. Required user choices use the
+existing run questions and resume the same work. The final handover includes the committed plan, source changes,
+test evidence and review results. Integration still requires the user's review.
+
+Planning and verification read the assigned design from its local Git commit, so later design synchronization
+does not silently change a running delivery. The implementation plan is stored at
+`docs/delivery/<goal-id>/implementation-plan.md` and remains part of the delivered repository history.
+
+EngineerOS reads the curated [ACP agent registry](https://agentclientprotocol.com/registry), caches it for 24 hours, and uses the registry's pinned distribution for the current platform. The catalog includes Codex, Claude, Gemini, GitHub Copilot, Goose, OpenCode, Qwen Code, Cursor, and other compatible agents as they are published. List the current catalog, prepare the selected agent, then pair the workspace:
+
+```sh
+npx --yes @engineeros/connector@latest agents
+npx --yes @engineeros/connector@latest agent gemini install
+npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard --agent gemini
+```
+
+Registry `npx` and `uvx` packages are prepared with their native package runner. Registry binaries are downloaded into `~/.engineeros/agents`, checked against the published SHA-256 digest when present, and launched from that managed location. The connector checks the selected distribution before pairing. Agent processes stay alive while the connector is active, project conversations reuse their ACP sessions, and response chunks reach Copilot as the agent produces them.
+
+## Pair an ACP coding agent
+
+Run the command from the repository the agent should work in:
+
+```powershell
+npx --yes @engineeros/connector@latest pair PAIRING-CODE --url http://localhost:8000 --workspace . --onboard --agent-name "My ACP agent" --agent-command my-agent --agent-args '["--acp"]'
+```
+
+`--agent-command` must start an ACP v1 agent over NDJSON stdio. `--agent-args` is a JSON array so arguments are passed without invoking a shell. Omit `--agent` and the custom command options to use the installed Codex CLI directly.
+
+Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.
+
+## Pair Forge
+
+[Forge](https://forgecode.dev) is driven through its own command line rather than ACP. Install it, sign in to a provider, then pair the workspace:
+
+```sh
+forge provider login
+npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard --agent-protocol forge
+```
+
+Forge runs its own agents, so `--agent` and `--agent-command` are rejected for this protocol. The connector selects the Forge agent that carries the access an assignment is entitled to: `sage` for read-only research, planning, assessment, and verification work, and `forge` for the writable implementation phase of a registered Goal. Pairing stops with the corrective command when Forge is missing, unauthenticated, or no longer provides both agents.
+
+Each EngineerOS session maps onto a Forge conversation, so project prompts and multi-stage assessments resume with their history intact. Token usage is reported per turn, measured as the growth of the conversation while the turn ran.
+
+Every model Forge offers through the providers you are signed in to is published to EngineerOS, named with its provider because the same model is offered by more than one, along with every reasoning effort Forge accepts. Forge takes the provider, model and reasoning effort of a run from the environment of its process, so the choice made in EngineerOS applies to that run alone: it does not change the model set with `forge config set model`, and it does not disturb a run beside it. The model and effort configured in Forge are marked as the default. Pairing stops when Forge offers no models, which means no provider is signed in: run `forge provider login`, then restart the connector.
+
+The connector registers the EngineerOS project artifact tools with Forge for the current user, which is the only scope Forge trusts without a person approving a file in the workspace, so nothing is written into the repository being worked on. Forge shares that one registration across every workspace and discovers the tools once, so the run each tool acts on is carried in the environment of the Forge process rather than in the registration. Concurrent runs stay separate, and a tool called outside an EngineerOS run is refused with the reason.
+
+## Agent roles and skills
+
+The selected ACP, Forge, or Codex agent is the execution engine. EngineerOS chooses a provider-neutral role for each activity and the connector injects exactly one bundled skill:
+
+- `research` uses `project-research` to answer questions from observed project evidence.
+- `assessment` uses the internal `assessment-maintenance` skill to inspect source without changing it and edit only the assigned assessment Markdown document.
+- `planning` remains read-only and uses one server-selected skill: `product-discovery`, `experience-design`, `solution-design`, `requirements-and-acceptance`, or `delivery-planning`. Product discovery covers both intent discovery and capability shaping; delivery planning covers accepted greenfield slices and brownfield changes.
+- `implementation` uses `implementation` with workspace-write access only for a registered Goal.
+- `verification` uses `independent-verification` with read-only access for artifact review and independent Goal proof.
+
+This is intentionally a small executable catalog. Skills for hypothetical release, quality, or agent-workflow phases are not advertised until EngineerOS has a workflow that can invoke them. Harness-wide access, evidence, clarification, and output rules remain outside skill bodies, so an assignment pays only for the specialized judgment it needs. Direct Codex runs also disable ambient skill instructions; ACP providers receive the selected EngineerOS skill in the assignment prompt rather than the rest of the catalog.
+
+The connector rejects a role whose access does not match the assignment before starting the agent. Role-specific sessions preserve useful context without mixing planning, research, implementation, or verification responsibilities. A shared interaction contract makes the Agent infer the current project situation, lead with the useful outcome, and suggest one concrete next activity only when it genuinely helps. User-visible responses refer neutrally to the Agent; provider and harness details remain operational metadata.
+
+## Onboard a workspace
+
+Create a connection command from **Project steering -> Connect workspace**, then run it inside the local folder:
+
+```sh
+npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard
+```
+
+The connector uploads a bounded ZIP snapshot for a safe file inventory, then stays online for deep assessments, rescans, and Goal Runs. Inventory never executes repository code. It excludes known secrets, dependency directories, build output, compiled binaries, files larger than 5 MB, agent-tool caches, Git metadata, and connector state before upload.
+
+From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select any combination of fifteen brownfield assessment domains, collectively covering 133 internal checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Reports include only material conclusions and actions; routine healthy checklist rows are not published. Capability entries state what they own, what they link to, and what they depend on. Connector `0.17.0` starts assessments with three parallel workers and accepts the run's UI-selected limit from three through eight for every coding-agent provider. It keeps one local assessment area at `.engineeros/assessment`: `assessment.md` is the canonical document, `sections/` holds the independently editable stage documents, `.work/` is the resumable transaction area, and an accepted update adds only a concise derived entry under `changes/`. A new run seeds each stage from its durable document, and a reconnect preserves any partially edited `.work` copy, so the coding agent updates affected content instead of regenerating the assessment. ACP agents such as OpenCode use isolated stage sessions within one persistent coding-agent process. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; report content is no longer streamed over the WebSocket or written into backend assessment JSON. The backend validates stage checkpoints so dependency fan-out remains authoritative, while the connector retains completed reports and reloads interrupted ACP or Codex sessions after reconnect when the coding agent supports session restoration. Transient ACP, app-server, provider-availability, and rate-limit failures receive two bounded attempts to continue the saved session without repeating completed inspection. A changed Git commit edits the same durable assessment, retains the prior commit in assessment history, and updates published artifacts in place. Connector reports and session checkpoints are tagged with their target commit so an earlier revision cannot leak into the update. If no assessment exists, EngineerOS creates the initial assessment identity and documents. Capability detail and project-specific compliance controls fan out after their catalogs. Final synthesis reads the connector-local Markdown files, then one completed bundle is revalidated, persisted, published as canonical artifacts, and archived locally. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. The connector prints each worker's safe activity and elapsed time every 30 seconds, stops a worker that produces no agent activity for ten minutes instead of waiting indefinitely, and asks the same agent session to repair the same document when structure or backend validation fails. Assessment cannot modify tracked workspace source outside its assigned document.
+
+Every backend `422` content-validation response is returned to the stage agent with the exact failed item. Distinct validation failures continue through correction and resubmission until the complete stage is accepted. Three repetitions of the same unresolved validation error stop the automatic loop while preserving the latest local report for retry. Authentication, cancellation, source drift, and transport failures remain operational errors rather than agent-correction prompts.
+
+If Codex reports that its refresh token was already used, stop every connector process using Codex before reauthenticating. Run `codex logout`, then `codex login` in a normal terminal, and restart one connector with `start --workspace ...`. The existing EngineerOS workspace pairing remains valid. The connector stops the failed ACP runtime and reports these recovery steps without exposing its internal stack trace.
+
+Assessment runs start by reporting whether an accepted assessment exists and how stale it is. Every assigned stage still runs against the current repository revision; durable reports do not contain a trustworthy dependency manifest, so the connector never presents an old section as newly inspected. Connector-owned files under `.engineeros` are ignored before drafts or context packs are created and therefore do not pollute repository change scans.
+
+After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
+
+Capability implementation planning uses committed local context in connector `0.32.0`. The synchronized
+`INDEX.md` links to the design, product intent, preparation context, decision revisions, implementation plans,
+current Facts and normalized Sources. A planning assignment carries the task, new guidance, record references
+and the expected snapshot revision; it does not resend those artifact bodies or an assignment-specific evidence
+copy. Before starting the agent, the connector checks the revision, saves the snapshot in local Git and supplies
+a `git show` pointer to that commit. All linked records are read from the same commit, so background sync does
+not change a running plan's input. The backend rechecks the context before saving a generated plan; stale input
+or invalid output leaves the accepted plan intact. No remote push is performed.
+
+Other greenfield generation prompts receive a bounded project-evidence manifest. EngineerOS normalizes uploaded text,
+PDF, DOCX, CSV, workbook, presentation, and image Sources, and the connector materializes normalized Markdown
+and available original attachments under an assignment-specific directory in `.engineeros/context/inputs/`.
+These files are connector-owned, ignored project
+context; the active coding agent reads them as untrusted evidence through ordinary file access. Only the most
+relevant Sources are included in each assignment. Normalized text is capped at one million characters and
+original attachments at 10 MB across the assignment so the WebSocket payload stays bounded; image, workbook,
+and presentation originals receive priority because their normalized text is only a descriptor. The connector
+removes the assignment directory after the Agent finishes.
+
+When material evidence or a user decision is missing, a generation Agent can return structured clarification
+questions instead of an artifact. EngineerOS stores and presents those questions, accepts free-text or newly
+uploaded evidence, and supplies answered clarifications when the same phase is retried. The connector does not
+hold a process or WebSocket request open while waiting for a user.
+
+The complete-product greenfield path performs that question review before each generation stage. After the user
+confirms the answers, connector `0.25.0` validates the Agent's complete structured Markdown bundle and atomically
+stores its files under `.engineeros/design/01-discovery` through `.engineeros/design/06-delivery`. Every stage has
+a manifest and remains directly editable by a human. Later stages read the approved earlier directories as their
+authoritative inputs. The planning Agent remains read-only: the connector, not the Agent process, owns the bounded
+local write, and an existing stage directory must be deleted explicitly before regeneration.
+
+Project prompts use resumable, role- and purpose-specific agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the role, purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.
+
+An empty or document-only folder establishes a greenfield baseline. A code-bearing folder is assessed as brownfield. Use **Rescan** in Steering after the local workspace changes.
+
+## Reconnect
+
+Connector 1.0.0 requires the updated EngineerOS backend. Upgrade both together, then restart the existing
+connector with `start`; its saved pairing remains valid. The WebSocket carries dispatch and control messages.
+Goal progress, assessment worker status, prompt output, failure reports and results use authenticated HTTP.
+There is no application JSON ping/pong. WebSocket protocol keepalive detects connection loss; quiet Goal work
+sends an HTTP heartbeat after 15 seconds without a progress update. Idle connectors need no application heartbeat.
+
+HTTP progress keeps one request in flight and retains the latest unsent state. Prompt deltas are ordered and
+bounded; a failed progress stream does not discard the final completed response. Requests have timeouts and
+bounded retries. Goal execution attempts and sequence numbers protect against delayed updates.
+
+Run the backend as **one worker and one replica**: dispatch sockets and pending prompt waiters currently live
+in process memory. The production image now uses one worker. Multiple backend workers require a shared dispatch
+broker before enabling them. An incompatible backend or connector fails with an upgrade instruction.
+
+```sh
+npx --yes @engineeros/connector@latest start --workspace .
+```
+
+Credentials are stored per workspace under `~/.engineeros/connectors` with owner-only permissions where supported.
+If a new pairing command is accidentally run from the same folder against the same EngineerOS server, the connector reuses this saved identity instead of creating another baseline assessment.
+
+## Self-check
+
+Connector 1.12.0 checks itself and reports the result to EngineerOS, so a local problem is visible in **Project steering -> Connect workspace** instead of only in this terminal. The checks cover the Node runtime, the saved pairing, whether the EngineerOS backend answers from this machine, whether the coding agent starts, the tool registry, and stuck local Goal jobs.
+
+The report is sent when the connector connects, every five minutes while it is idle, and once more when a startup problem is about to stop it, which is the case EngineerOS could not see before: the workspace simply appeared offline. Run the same checks locally at any time, paired or not:
+
+```sh
+npx --yes @engineeros/connector@latest doctor --workspace .
+```
+
+The command prints every check with its reason and remedy, sends the report when the workspace is paired, and exits non-zero when a check failed.
+
+## Local Git history
+
+Pairing or starting connector 0.31.0 initializes a local Git repository when the project has none and creates its initial commit from source files and durable design/assessment artifacts. An empty project also gets a usable baseline. Existing repositories and their pending source changes are preserved. Git must be installed; no remote is created and nothing is pushed.
+
+As design context syncs, the connector commits new, changed and deleted durable artifact files locally. These explicit artifact paths are included even though connector runtime state is ignored. Source generated by a capability is committed by the existing implementation and verification workflow on its capability branch. Environment secrets, credentials, dependency/build directories, context indexes and temporary handover files remain excluded. Identical snapshots produce no extra commits, and artifact sync waits while an implementation run is active.
+
+## Run Goals
+
+From capability delivery, choose **Implement capability** and an online coding connector. EngineerOS prepares any missing implementation plan from the saved design, validates its prerequisites, and starts the run. **Preview plan** is optional; the detailed plan remains available without becoming a separate mandatory document review.
+
+The connector coordinates implementation, independent testing and independent code review. Native implementation subagents may work on independent tasks when the selected coding harness supports them. Testing and review run as separate read-only processes after the implementation is committed. At most two repair-and-review cycles follow the initial review; completed allowances survive resume. Repository finalization has its own single recovery attempt. Unresolved findings are then handed back with failed evidence instead of starting another repair. The handover includes the implementation report, exact revision, changed files and final check reports; persistent failures remain failed.
+
+Reuse existing shared foundations. A necessary out-of-scope prerequisite requires a recorded approval through `engineeros_request_input` with `decision_area: scope_expansion`, a stable question key, the precise addition and its reason and impact. Each run permits at most two expansion requests, including rejected or dismissed requests. Select **Approve scope expansion** in EngineerOS to authorize that specific addition; other answers do not authorize work. These approvals reach the implementer, independent reviewers and final handover. They do not reset the repair allowance or rewrite the original frozen Goal. Further expansion requires a separate Goal.
+
+When a consequential choice is missing, the implementation agent calls `engineeros_request_input` and finishes its turn. Answer the question in the active run using a suggestion or your own words. The connector keeps heartbeats active, preserves the workspace and resumes with the saved answer. Dismissal and cancellation never count as answers. Cancellation stops all workers in the run. This feature requires the updated backend and connector; it does not deploy the product or automatically approve its handover.
+
+Keep the connector online to receive Goals assigned from EngineerOS. Each run explicitly selects one workspace
+mode. `local_branch` creates or reuses the capability branch in the connected repository, runs with its exact
+local dependencies and properties, and returns to the original branch after a clean committed run. It is the
+default for a dedicated agent machine. Work left uncommitted on the current branch, staged or untracked, is
+stashed before the Goal branch is created and reapplied when the repository is handed back, so it never blocks
+a Goal and never becomes part of it. Ignored files are left in place. Work that no longer applies cleanly stays
+in `git stash list` with its recovery command reported on the run.
+`isolated_worktree` creates one durable worktree at `<project>/.engineeros/goals/<goal-id>` and reuses it
+across retries. The worktree shares Git configuration and hooks and copies individual ignored local configuration
+files; ignored dependency and build directories are not duplicated. The coding-agent process inherits the
+connector environment in both modes. Cancellation stops the agent. The connector returns changed paths, a bounded
+diff, and the exact repository ZIP; a human still performs independent attestation. Accepted work fast-forwards
+into an unchanged clean connected branch, or cherry-picks the complete Goal commit range onto a clean branch that
+advanced, then refreshes the workspace snapshot. Dirty or conflicting workspaces are never overwritten: the Goal
+branch remains available for explicit review and merge.
+
+During the writable implementation phase, Codex receives an authenticated EngineerOS MCP server automatically. It can list, read, create, update, reclassify, soft-delete, and materialize project artifacts into canonical Product records through the same repository boundary used by Copilot. The backend accepts those calls only while the assigned Goal is running. Read-only project prompts and the independent verification phase do not receive mutation tools.
+
+### Resume a failed or interrupted Goal run
+
+Connector 0.34.0 keeps new isolated Goal worktrees inside the project at `.engineeros/goals/<goal-id>`.
+Execution checkpoints live at `.engineeros/runs/<run-id>`. Start the connector with its existing pairing,
+open the Goal's run panel and select **Resume run**. A disconnected running run becomes resumable after
+90 seconds without a heartbeat. Offline resume requests wait for the assigned connector to reconnect.
+
+Resume preserves the run ID, frozen assignment, branch, files and completed implementation. It restores the
+agent session when supported and reruns interrupted verification. A completed result is retained for another
+upload attempt; changing the code causes it to be verified again. Existing worktrees are reused through Git's
+registry, so an upgrade does not move your current work. A missing workspace or corrupt checkpoint must be
+restored before resuming. Submitted results and final acceptance receipts retain their existing review flow.
+
+## Local context engine
+
+The connector keeps a local index for each workspace under `~/.engineeros/context/<connector id>/workspaces/`: file classifications, symbols, document headings, and import relationships for every safe file. Separating indexes by resolved workspace keeps the source checkout and concurrent Goal worktrees from replacing one another. An index is built at onboarding, refreshed incrementally from file digests when EngineerOS triggers a workspace refresh, and re-checked before every assignment. Symbols in Python, JavaScript, TypeScript, Go, Java, Rust, Ruby and PHP come from tree-sitter syntax trees, using grammars shipped with the connector, so methods inside classes are indexed and `engineeros_read_symbol` returns exactly one declaration; other languages use line patterns.
+
+Before a workspace assessment stage runs, the connector also extracts repository facts from that index without a model: routes and pages, data models and migrations, integrations declared in dependency manifests, configuration keys, delivery and runtime files, and files that check authentication. They are cached per commit in `.engineeros/context/repository-facts.json`. Each stage receives only a bounded slice of the facts it starts from, with no full copy for an agent to read at once, and the capability catalog receives draft capability areas with their locations, so stages confirm a known inventory instead of rediscovering it.
+
+Every assignment prompt arrives with a bounded, task-ranked Markdown working set. It names the most relevant paths, symbol and heading locations, local dependencies, direct consumers, and candidate tests, followed by a pointer to the durable source map at `.engineeros/context/source-map.md`. The connector ranks from the assignment's focused context query, frozen Goal packet, assessment stage identity, or current project request as appropriate. It never pastes source-file contents into the prompt; the Agent reads deeper through the source map, the listed files, assessment sections, ordinary file tools, or the attached `engineeros_*` MCP tools. Ranking is structural and lexical, using indexed paths, symbols, summaries, and imports; it does not generate or store embeddings.
+
+Context preparation is a launch prerequisite for every role. The connector refreshes the correct workspace index, verifies that the source map exists, and stops before starting an agent with an actionable error when pairing identity, indexing, or map generation is unavailable. Resumed project sessions also receive a bounded `Session Memory` digest of relevant earlier turns in the same session, kept under `~/.engineeros/context/<connector id>/sessions/`, so follow-up prompts build on prior conclusions instead of re-deriving them. Entries carry a derived kind (fix, decision, change, or conclusion), and cross-session recall is stamped with its source session and last-active time.
+
+Every direct Codex assignment — project prompt, assessment, Goal implementation, and independent verification — receives the local read-only context MCP server with `engineeros_search`, `engineeros_outline`, `engineeros_read_symbol`, `engineeros_similar`, `engineeros_blast_radius`, and `engineeros_recall`. Registry-backed ACP adapters receive the same runtime-workspace server through `session/new` and `session/load`. Only a writable Goal implementation receives the authenticated EngineerOS artifact MCP server; project prompts, assessments, and verification never receive mutation tools. Custom ACP commands receive no injected servers because they have no registry MCP contract.
+
+After Goal implementation commits its isolated worktree change, the connector rebuilds context from that exact post-commit workspace before starting the independent verifier. Verification therefore receives the current task-ranked working set plus a bounded `Change Impact` section naming changed files, direct importers, and candidate tests rather than relying on the pre-change index. `engineeros_similar` helps the Agent extend existing functions, classes, and types instead of duplicating them. Stored symbol outlines omit literal constant values, MCP search responses are capped at one hundred files, and the index, source map, prompt context, and session memory remain on the local computer.
+
+## Local design artifacts
+
+Connector 0.28.0 synchronizes persisted design records into
+`.engineeros/design/projects/<project-id>/`, with `INDEX.md` linking the named
+Markdown artifacts and their current review status. Sync runs on connection,
+every ten seconds, and before project prompts and Goal execution. Goal worktrees
+receive their own copy. Assignments point the agent to the index explicitly.
+
+The database remains authoritative. Confirm edits through EngineerOS Copilot;
+local changes are overwritten by the next successful sync. Renames and deletions
+remove outdated Markdown files from this managed directory. An offline connector
+refreshes when it reconnects. The backend must provide the matching design-context
+endpoint; sync failures are reported and block new agent tasks from using stale context.
+
+## Autonomous work scan
+
+Connector 1.23.0 can tell EngineerOS what this workspace should deliver next. It scans only when the
+autonomy policy for the project asks it to: EngineerOS answers each five-minute self-check with whether
+it wants a scan, and an autonomy policy that is off, out of budget or already running a Goal never
+causes one. Turn it on, and off again, in **Project steering -> Autonomy**.
+
+When a scan is requested, the connector waits until nothing else is running here — no assessment stage,
+no prompt, no local Goal job — and then reads evidence that is already on disk: the synced design index,
+the local assessment, and Goal runs that stopped. One read-only agent turn ranks that evidence and names
+at most five capabilities worth starting, each with its reason. The turn has no write, command or tool
+access, and the scan repeats at most every thirty minutes.
+
+The connector never starts work of its own. Candidates are reported as evidence; EngineerOS re-validates
+every one against its own records, applies the policy, budget and concurrency limits, and decides whether
+to dispatch a Goal. A candidate naming a capability EngineerOS never published to this workspace is
+discarded before it is sent. A failing scan backs off like other maintenance and names itself in the
+self-check.
+
+Each report comes back with what EngineerOS turned down. The next scan asks for different work and drops
+a refused candidate even if the agent repeats it. When neither the workspace nor those refusals have
+changed, the shortlist is repeated from memory and no agent turn is spent at all, so an idle workspace
+costs nothing to keep watching.
+
+## Run spend ceiling
+
+Repair cycles bound how often work is retried, and a run that goes quiet is stopped after ten minutes.
+Neither bounds a run that keeps producing output while spending, which matters once EngineerOS starts
+Goals without anyone watching. Every delivery run therefore stops at **5,000,000 tokens**, counted across
+resumes from the saved run checkpoint and stated to the agent in its execution rules.
+
+Reaching the ceiling is a stopping point, not a crash: the committed changes and unresolved findings are
+handed over for review exactly as they are when the repair budget runs out, and the spend already made is
+reported to EngineerOS. Set `ENGINEEROS_RUN_TOKEN_CEILING` to a different whole number of tokens to raise
+or lower it for this machine.
+
+## Requirements
+
+Node.js 22 or newer, Git, and an authenticated agent. `npx` distributions use npm, `uvx` distributions require uv, and binary archives require `tar` (`unzip` for ZIP files on Linux). Registry agents report their own authentication prerequisites when they start.
+
+## Execution profiles
+
+EngineerOS can set a workspace default model and reasoning effort, then override either value for an individual Goal. The same workspace default is used for assessments, Copilot, and generated artifacts. The connector passes the resolved values to Codex CLI and reports unsupported profiles instead of silently ignoring them.
+
+Codex connectors advertise `gpt-5.6-sol` and `gpt-5.6-terra` by default. Override the choices shown in EngineerOS before starting the connector:
+
+```sh
+ENGINEEROS_AGENT_MODELS="model-a,model-b" npx @engineeros/connector start --workspace .
+```
+
+## Codex CLI compatibility
+
+The connector prints the exact Codex CLI version it will use before connecting. If the
+configured model requires a newer CLI, update Codex and restart the connector:
+
+```sh
+npm install -g @openai/codex@latest
+codex --version
+npx @engineeros/connector start --workspace .
+```
+
+## Supervisor recovery
+
+The workspace runner monitors worker health separately from progress reporting. Continuous reporting failures pause coding after one minute; missing worker health is detected after ninety seconds. Recovery preserves the sandbox and checkpoint. It allows one restart per failure category and at most two per run, with a cooldown and storage check before restarting.
+
+Unknown runtime failures may use one read-only LLM diagnosis per run through the configured agent, with a two-minute deadline. Known filesystem and network faults do not call an LLM. Diagnosis recommends retrying the checkpoint or a manual fix; it does not execute generated commands or modify the connector. Repeated failures stop automatic recovery. Inspect `runner status` and `.engineeros/runner/recovery/<run-id>.json`, fix the reported cause, then explicitly resume the existing run. Recovery budgets are retained.
+
+Verification results are cached per commit and role. Completed checks are reused. An interrupted check requires inspection before a new revision; it is not automatically billed again. Existing workers must load the new connector code before these protections apply.
+
+## Optional tool and plugin inventory
+
+Connector 1.7 advertises a curated candidate catalog alongside the operator-managed inventory. The catalog covers code intelligence, design, work management, source control, documentation, research, API development, browser testing, quality and security, data, infrastructure, observability and development environments. Candidate entries are metadata only: they are not installed, authenticated, admitted, started or exposed to coding agents.
+
+The catalog includes CodeGraph, Serena, JetBrains IDE MCP, ast-grep, Figma, Storybook, Miro, Lucid, Linear, monday.com, Atlassian Rovo, YouTrack, Notion, Slack, GitHub, GitLab, Context7, Postman, Exa, Tavily, Firecrawl, Perplexity, Playwright, Chrome DevTools, BrowserStack, Semgrep, SonarQube, Snyk, Gitleaks, Trivy, PostgreSQL MCP, Supabase, Terraform, AWS, Azure, Cloudflare, Vercel, Sentry, Grafana, Datadog, PagerDuty, Renovate, Dev Container CLI and Docker MCP Gateway. Each entry records its category, selection group, activation condition, eligible workflow profiles, provenance and default policy. Overlapping selection groups are alternatives, not permission to load every provider.
+
+Inspect the catalog and locally registered providers without starting software:
+
+```sh
+engineeros-connector tools list --workspace PATH
+engineeros-connector tools register /absolute/path/manifest.json --workspace PATH
+engineeros-connector tools disable PROVIDER_ID --workspace PATH
+engineeros-connector tools disable all --workspace PATH
+engineeros-connector tools enable PROVIDER_ID --workspace PATH
+engineeros-connector tools remove PROVIDER_ID --workspace PATH
+engineeros-connector tools sign-in PROVIDER_ID --workspace PATH
+engineeros-connector tools auth-status PROVIDER_ID --workspace PATH
+engineeros-connector tools sign-out PROVIDER_ID --workspace PATH
+```
+
+After pairing connector 1.8 or newer, open **Project → Steering → Local workspace → Tools and plugins** to search the catalog and control registered providers. The web UI can enable, disable and remove registrations through the authenticated connector session. Enabling and removal require confirmation. Registration remains local because its evaluated manifest contains machine paths and integrity metadata that are never advertised to EngineerOS.
+
+Use `enable all` to clear the global disable. Registration never installs packages or executes a provider. Replacing a pin requires explicit removal and registration. Registry files live beside the user-owned connector configuration as `<workspace-key>.tools.json`, outside the repository. The connected workspace displays their inventory, refreshed through authenticated heartbeats. Stop any abandoned operator update before removing its `.tools.json.lock` file.
+
+Manifests are strict internal JSON configuration with these required fields:
+
+| Field | Required value |
+| --- | --- |
+| `id`, `name`, `provider`, `capability_class` | Stable lowercase ID, display labels and `tool`, `skill` or `agent`. |
+| `source`, `version`, `license` | Credential-free HTTPS source, exact semantic version and license. No `latest` or version range. |
+| `launch` | For `stdio` or skill `file`: `transport`, absolute `entrypoint`, absolute `package_json` and lowercase `sha256` of the entrypoint. For `https`: `transport` and credential-free `endpoint`. No commands, arguments or environment values are accepted. |
+| `platforms` | Array containing supported `win32`, `linux` and/or `darwin`. |
+| `permissions` | `workspace` (`none`, `read`, `write`), `process` boolean, `network` HTTPS URL array, `browser` (`none`, `isolated`), `secrets` reference-name array and `external_mutations` boolean. These record requests, not runtime grants. |
+| `authentication` | `none`, operator-owned `external` instructions, or `oauth` with exact scopes and either dynamic client registration or a provider-issued public client ID. Secret values are never accepted in a manifest. Older manifests without this field remain loadable but report setup required for HTTPS or secret-bearing providers. |
+| `profiles` | Array of `discovery`, `research`, `implementation`, `verification`, `handover`. |
+| `tasks`, `exclusions` | Arrays of lowercase task IDs; at least one eligible task. |
+| `tools` | Array of objects with `name` (`provider-id:operation_name`), concise `description`, and `response_mode` (`summary` or `reference`). |
+| `policy` | `approval_required: true`, `timeout_ms` from 100 to 30000, `retry_limit` 0 or 1. Reserved for bounded provider adapters; inspection executes nothing. |
+| `evidence` | `metadata-only`. |
+| `evaluation` | `status` (`experimental` or `standard`) and a real evidence `reference`. Standard status requires completed comparative evaluation. |
+
 At most 16 providers may be registered per workspace even though the read-only catalog is larger. Local files must be regular files (resolve symlinks before registration). Inspection compares installed package metadata and entrypoint bytes; it does not verify the entire dependency tree. Local version/hash mismatches and unavailable files report preparation actions. Registered HTTPS providers may use connector-managed OAuth: open **Tools and plugins**, choose **Sign in**, and complete consent in the browser opened on the connected machine. The connector follows MCP authorization discovery, uses PKCE with a loopback callback, and advertises only status, scopes and expiry. Windows protects the credential payload with current-user DPAPI outside the repository; unsupported platform keychains fail closed. Sign out deletes the local credential but does not remove the provider registration. MCP protocol, runtime and index health remain unchecked until a provider pilot implements them. Every entry remains execution-disabled, even if authentication succeeds. Launch paths, endpoints, tokens, authorization codes and raw file errors are excluded from advertised inventory. Do not put secrets in labels, URLs, descriptions or evidence references.