machine-bridge-mcp 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.9.0 - 2026-07-12
+
+### Agent context and local workflows
+
+- Add `agent_context`, a bounded bootstrap tool with Codex-compatible instruction precedence: unrestricted `CODEX_HOME`/`~/.codex` guidance, then project root-to-target scopes, selecting the first non-empty `AGENTS.override.md` or `AGENTS.md` candidate per directory under a default 32 KiB combined budget. Add hierarchical `.machine-bridge/agent.json` manifests plus an optional unrestricted user manifest at `~/.config/machine-bridge-mcp/agent.json` for custom candidate priority and bounds.
+- Add `list_local_skills` and `load_local_skill` with Codex-style progressive disclosure. Default discovery scans target-to-root `.agents/skills`, unrestricted user/admin roots, and canonicalized symlinked skill directories; invalid metadata is skipped with bounded warnings. Skill loading returns instructions and a relative file inventory without implicitly executing scripts.
+- Add `list_local_commands` and direct-argv `run_local_command`. Nearest manifests can override or remove inherited commands, caller arguments require manifest opt-in, and callers cannot increase the manifest timeout ceiling.
+
+### Architecture, security, and tests
+
+- Extract agent discovery into `AgentContextManager` rather than expanding transport or runtime dispatch responsibilities. Keep a static MCP catalog across Worker and stdio transports so host-side caching and filtering do not require dynamic per-skill tools.
+- Reject escaping instruction/config paths, unknown manifest fields, out-of-policy skill symlink targets, symbolic-link skill entrypoints, ambiguous skill names, oversized content/argv, and execution attempts under non-execution profiles. Document that repository instructions and skills are untrusted content and that registered commands are convenience aliases, not a sandbox or approval boundary.
+- Add regression coverage for global/project override selection, empty-candidate fallback, custom priority, instruction-byte ceilings, target-to-root skill discovery, symlinked skill folders, invalid metadata warnings, command override/removal, literal argument handling without shell parsing, timeout ceilings, path escape denial, and execution-profile denial. Update server instructions, architecture, security, testing, and operator documentation for the new bootstrap workflow.
+
+## 0.8.2 - 2026-07-11
+
+### Relay reliability and protocol correctness
+
+- Add a deadline for WebSocket connection establishment so a transport stuck in `CONNECTING` cannot freeze automatic reconnection indefinitely. Sustained-outage reminders now run on an independent exponential-backoff timer capped at 15 minutes instead of appearing only when another reconnect event happens.
+- Handle Worker `{type:"error"}` messages explicitly. A daemon hello timeout is classified as transient and retried; unknown protocol errors, duplicate hello messages, identity/version mismatch, and authentication rejection terminate with actionable guidance instead of becoming an `unknown websocket message` warning.
+- Validate daemon WebSocket JSON as a non-array object before field access. Invalid JSON closes with code 1007, non-object/unknown/duplicate protocol messages close with code 1002, and active daemon replacement semantics remain unchanged.
+
+### Logging, tests, and documentation
+
+- Replace default outage/recovery JSON field dumps with readable duration, attempt, cause, automatic-recovery, and long-outage action text. Exact seconds, error classes, retry delays, and raw transport details remain debug-only. Advance the autostart log schema so historical 0.8.1-format lines are separated into the bounded owner-only legacy snapshot. Treat a service-style daemon-only start that finds the workspace daemon already running as a silent idempotent success, preventing repeated lock warnings and duplicate readiness output from accumulating in service logs.
+- Add deterministic tests for stalled connection attempts, autonomous reminder backoff, retryable versus fatal relay error messages, close-reason classification, and runtime control-message routing. Extend live Worker integration coverage to invalid JSON, non-object messages, duplicate hello, and unknown authenticated messages. Enable TypeScript unused-local and unused-parameter checks to prevent dead Worker code from accumulating.
+- Update architecture, operations, logging, testing, and README guidance to match the implemented state machine and operator-facing behavior. Add a repository automation contract separating code/test/commit/push work from npm publication, global CLI installation, Worker deployment, credential rotation, and daemon/service operations; the owner performs those live release steps explicitly. Improve release-check diagnostics so a missing local or remote version tag is reported distinctly from a tag pointing at the wrong commit, with the required `release:publish` step named directly.
+
 ## 0.8.1 - 2026-07-11
 
 ### Fixed

package/CONTRIBUTING.md

@@ -4,15 +4,23 @@ This repository treats every Git-tracked or nonignored repository file as releas
 
 ## Required for every release-relevant change
 
-Before a change is merged to `main`:
+Before the reviewed code is pushed to `main`:
 
 1. bump `package.json` to a version newer than the latest reachable `v*` tag;
 2. add the matching dated section to `CHANGELOG.md`;
 3. run `npm run check`, `npm audit`, `npm audit --omit=dev`, and `npm run worker:dry-run`;
 4. inspect the complete diff and the npm package manifest;
-5. push the reviewed commit to GitHub;
-6. create the matching Git tag and GitHub Release;
-7. publish the same version to npm.
+5. commit and push the reviewed change to GitHub.
+
+The release operator then creates the matching Git tag and GitHub Release and publishes the same version to npm. These release actions are not implicit coding-agent tasks. Unless the user explicitly requests them in the current task, automation must not publish or alter npm versions, create tags or releases, install the CLI globally, deploy the Worker, rotate credentials, mutate live deployment state, or start/stop/install/remove the daemon or autostart service. See [AGENTS.md](AGENTS.md) for the repository automation contract.
+
+After npm publication, the standard machine update is:
+
+```bash
+npm install -g --allow-scripts=esbuild,workerd,sharp machine-bridge-mcp@latest && machine-mcp
+```
+
+The npm command updates the global CLI. Normal `machine-mcp` startup checks the Worker deployment hash, expected version, and health, redeploys when necessary, and reconciles the daemon/autostart flow.
 
 `npm run release-impact:check` enforces the version and changelog parts. It fails when release-relevant files changed after the latest version tag but the package version was not advanced.
 

package/README.md

@@ -108,6 +108,37 @@ machine-mcp stdio --workspace /path/to/project
 
 The stdio server writes only JSON-RPC messages to stdout and operational logs to stderr. See [docs/CLIENTS.md](docs/CLIENTS.md) for the host/model distinction and transport trade-offs.
 
+## Agent instructions, local skills, and command registry
+
+For substantive workspace tasks, clients can call `agent_context` for the relevant file or directory. Its default instruction discovery mirrors Codex: under unrestricted policy it first checks `CODEX_HOME` or `~/.codex`, then walks from the project root to the target directory, selecting the first non-empty `AGENTS.override.md` or `AGENTS.md` in each scope. Deeper guidance has higher precedence, and the default combined budget is 32 KiB.
+
+Skill discovery also follows Codex-style progressive disclosure. By default, Machine Bridge scans `.agents/skills` from the target directory through the project root; unrestricted policy additionally enables `~/.agents/skills` and, on Unix-like systems, `/etc/codex/skills`. `agent_context` initially returns bounded metadata, while `load_local_skill` returns the selected `SKILL.md` and file inventory without executing anything implicitly.
+
+A project can add custom instruction candidates, explicit skill roots, and registered commands with `.machine-bridge/agent.json`:
+
+```json
+{
+  "version": 1,
+  "instruction_files": [
+    "PROJECT.override.md",
+    "AGENTS.override.md",
+    "AGENTS.md"
+  ],
+  "instruction_max_bytes": 65536,
+  "commands": {
+    "check": {
+      "description": "Run repository validation.",
+      "argv": ["npm", "run", "check"],
+      "cwd": ".",
+      "timeout_seconds": 600,
+      "allow_extra_args": false
+    }
+  }
+}
+```
+
+`instruction_files` is a priority list: each directory contributes only its first non-empty candidate. Deeper manifests override earlier settings and can remove an inherited command with `null`. `run_local_command` executes registered commands as direct argv processes without shell parsing and is available only when direct execution is enabled. See [Agent context, local skills, and registered commands](docs/AGENT_CONTEXT.md) for the complete contract.
+
 ## Policy controls
 
 The default is `full`. Narrow or customize it with explicit flags:
@@ -233,6 +264,10 @@ The exact `tools/list` response reflects the active local policy. Definitions co
 
 - `server_info`
 - `project_overview`
+- `agent_context` — effective instructions, skill summaries, and registered commands for a target path
+- `list_local_skills`
+- `load_local_skill` — load instructions and file inventory without implicit execution
+- `list_local_commands`
 - `list_roots`
 - `list_dir`
 - `list_files`
@@ -270,6 +305,7 @@ Managed jobs are non-interactive and persist independently of the MCP connection
 
 ### Processes
 
+- `run_local_command` — direct argv execution of a manifest-registered command
 - `run_process` — one-shot argv execution without a shell
 - `start_process`
 - `read_process`
@@ -335,7 +371,7 @@ Default state roots:
 
 State/config writes use owner-only temporary files, flushes, and atomic rename. Malformed state is retained as a bounded corrupt backup before reconstruction. Resource source paths are redacted from `status` output. Active managed-job plans are owner-only and are deleted after a terminal result; bounded redacted results are retained temporarily. Uninstall validates markers, canonical paths, active locks, workspace/source exclusions, and known contents before recursive deletion.
 
-Default foreground logs report authenticated relay readiness, persistent degradation, and recovery summaries rather than raw WebSocket callbacks. Brief self-healing disconnects and close codes/reasons are debug-only. Every per-tool event—including success, failure, cancellation, and slow-call timing—also appears only at `--log-level debug` or `--verbose`. Background services use `warn`, so ordinary tool outcomes and brief network changes do not fill daemon logs. Log messages and structured fields are bounded, secret-like keys and known token formats are redacted, and tool arguments/results are not written. See [docs/LOGGING.md](docs/LOGGING.md) and [docs/OPERATIONS.md](docs/OPERATIONS.md).
+Default foreground logs report authenticated relay readiness, readable persistent-degradation summaries, and recovery rather than raw WebSocket callbacks or JSON field dumps. Brief self-healing disconnects and close codes/reasons are debug-only. Stalled connection attempts have a deadline, and sustained-outage reminders use autonomous exponential backoff. Every per-tool event—including success, failure, cancellation, and slow-call timing—also appears only at `--log-level debug` or `--verbose`. Background services use `warn`, so ordinary tool outcomes and brief network changes do not fill daemon logs. Log messages and structured fields are bounded, secret-like keys and known token formats are redacted, and tool arguments/results are not written. See [docs/LOGGING.md](docs/LOGGING.md) and [docs/OPERATIONS.md](docs/OPERATIONS.md).
 
 ## Development and verification
 
@@ -350,7 +386,7 @@ npm pack --dry-run
 
 `npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, local path/write/process/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
 
-See [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
+See [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
 
 ## Uninstall
 

package/SECURITY.md

@@ -51,6 +51,16 @@ The default for newly selected workspaces is `full`, which prioritizes ease of u
 
 For untrusted repositories or instructions, run the bridge inside a disposable VM/container or under a dedicated low-privilege OS account. On macOS and Windows, this external isolation is especially important. The project does not claim an in-process OS sandbox.
 
+## Agent instructions, skills, and command manifests
+
+Repository and user instruction files are untrusted content from the model's perspective. `agent_context` returns their text in deterministic precedence order but does not certify correctness or safety. A malicious `AGENTS.md`, custom instruction file, or `SKILL.md` can attempt prompt injection or recommend destructive operations. Use only trusted repositories and skill roots, or isolate the bridge externally.
+
+Skill loading is non-executing. `load_local_skill` returns an entrypoint and bounded file inventory; scripts remain inert until a separate process or command tool is called. Symlinked skill directories are followed only after canonical path-policy validation, while symbolic-link `SKILL.md` entrypoints are rejected. Traversal, cycles, content, summaries, and inventory are bounded.
+
+Registered commands are available only under direct-execution-capable policy. They use argv spawning rather than shell parsing, reject undeclared caller arguments, and enforce the manifest timeout as a ceiling. They are not an approval or sandbox boundary: a repository-controlled package script, interpreter, compiler, or executable can still run arbitrary code with local-user authority. Deeper manifests can override or remove inherited commands, so callers must obtain context for the actual target path rather than assuming the repository-root registry applies everywhere.
+
+The remote MCP host remains an independent boundary. Machine Bridge can advertise these tools and instruct the model to bootstrap with `agent_context`, but it cannot force a host to expose or invoke them, and it cannot bypass host confirmation or refusal.
+
 ## Filesystem exposure
 
 Direct filesystem scope is profile-dependent. The default `full` profile is unrestricted. The `agent`, `edit`, and `review` profiles confine direct filesystem tools to the canonical selected workspace, including symbolic-link resolution.

package/docs/AGENT_CONTEXT.md

@@ -0,0 +1,206 @@
+# Agent context, local skills, and registered commands
+
+The default compatibility target is the current OpenAI Codex guidance for repository instructions and filesystem skills.
+
+Machine Bridge exposes a stable agent bootstrap layer so an MCP client can use repository instructions and local workflows without requiring one dynamically named MCP tool per skill or command.
+
+The default discovery rules intentionally track current Codex conventions where practical. Machine Bridge also adds a JSON manifest for custom instruction priority, additional skill roots, and named local commands.
+
+This does not make a remote MCP session identical to a locally installed coding agent. The MCP host can independently filter tools, require confirmation, truncate results, or decline calls before they reach Machine Bridge. The bridge cannot alter or bypass those host decisions.
+
+## Tool model
+
+Five tools form the agent-context surface:
+
+- `agent_context` discovers effective instructions, skill summaries, and registered commands for a target path;
+- `list_local_skills` searches discovered `SKILL.md` or `skill.md` bundles;
+- `load_local_skill` returns one skill entrypoint plus a bounded relative file inventory;
+- `list_local_commands` returns the effective command registry;
+- `run_local_command` executes one registered command as a direct argv process.
+
+The server instructions tell MCP clients to call `agent_context` before substantive workspace work. This is behavioral guidance, not a protocol-enforced precondition. Every file, Git, mutation, and process tool therefore retains its own policy enforcement.
+
+## Instruction scope and precedence
+
+For a target path, Machine Bridge chooses the nearest ancestor containing `.git` as the project scope root. If no Git marker is found, a target inside the configured workspace uses the workspace root; an unrestricted target outside the workspace uses the target directory.
+
+The default instruction candidates, in priority order, are:
+
+```json
+[
+  "AGENTS.override.md",
+  "AGENTS.md"
+]
+```
+
+Discovery then works as follows:
+
+1. under unrestricted policy, read the first non-empty candidate in `CODEX_HOME` or `~/.codex`;
+2. walk from the project scope root to the target directory;
+3. in each directory, apply its optional `.machine-bridge/agent.json` first;
+4. select only the first non-empty instruction candidate in that directory;
+5. concatenate selected files from global to root to leaf, so later directories have higher precedence.
+
+Empty candidates are skipped. Only one instruction file is selected per directory. This matches the important Codex override behavior: `AGENTS.override.md` suppresses `AGENTS.md` in the same directory, while deeper directories override broader guidance.
+
+The combined instruction budget defaults to 32 KiB. Once the budget would be exceeded, discovery stops and returns `instructions_truncated: true`. A manifest can raise or lower the budget within the hard 2 MiB ceiling.
+
+Global instruction discovery is disabled under workspace-confined profiles because reading `~/.codex` would otherwise bypass the profile's direct-filesystem boundary. Project instructions still work in every profile.
+
+## Custom instruction priority
+
+A manifest may replace the candidate list. The list is priority order, not a list of files to concatenate from the same directory:
+
+```json
+{
+  "version": 1,
+  "instruction_files": [
+    "LOCAL.override.md",
+    "AGENTS.override.md",
+    "AGENTS.md",
+    ".github/agent-guidance.md"
+  ],
+  "instruction_max_bytes": 65536
+}
+```
+
+For each directory, Machine Bridge selects the first non-empty file in that list. Candidate paths must be relative and their canonical targets must remain inside the directory being inspected.
+
+## Configuration format
+
+A project configuration lives at `.machine-bridge/agent.json`. Relative skill roots and command working directories are resolved against the directory containing `.machine-bridge`, not against the hidden configuration directory itself.
+
+```json
+{
+  "version": 1,
+  "instruction_files": [
+    "PROJECT.override.md",
+    "AGENTS.override.md",
+    "AGENTS.md"
+  ],
+  "instruction_max_bytes": 65536,
+  "skill_roots": [
+    ".agents/skills",
+    ".codex/skills"
+  ],
+  "commands": {
+    "check": {
+      "description": "Run the repository validation suite.",
+      "argv": ["npm", "run", "check"],
+      "cwd": ".",
+      "timeout_seconds": 600,
+      "allow_extra_args": false
+    },
+    "test-file": {
+      "description": "Run one test file selected by the caller.",
+      "argv": ["node", "--test"],
+      "cwd": ".",
+      "timeout_seconds": 120,
+      "allow_extra_args": true
+    }
+  }
+}
+```
+
+Supported top-level fields are:
+
+- `version`: required and currently fixed at `1`;
+- `instruction_files`: non-empty priority-ordered relative candidates;
+- `instruction_max_bytes`: combined instruction budget from 1 KiB through 2 MiB;
+- `skill_roots`: explicit skill directories; when present, this replaces inherited/default roots;
+- `commands`: named command definitions merged with inherited commands.
+
+Configuration is evaluated from global to project root to target directory. A deeper definition replaces the inherited value. A deeper command value of `null` removes that command:
+
+```json
+{
+  "version": 1,
+  "commands": {
+    "deploy": null
+  }
+}
+```
+
+Unknown fields are rejected so misspellings do not silently weaken the intended workflow.
+
+Under unrestricted policy only, `~/.config/machine-bridge-mcp/agent.json` acts as the initial user-level manifest. Relative paths in that file are resolved from the user's home directory.
+
+## Skill discovery
+
+Without an explicit `skill_roots` setting, Machine Bridge uses Codex-compatible filesystem locations:
+
+- `<target>/.agents/skills`;
+- every ancestor's `.agents/skills` through the project root;
+- under unrestricted policy, `~/.agents/skills`;
+- under unrestricted policy on Unix-like systems, `/etc/codex/skills`.
+
+An explicit `skill_roots` list can add compatibility with other layouts, such as `.codex/skills`, or narrow discovery to selected directories.
+
+Machine Bridge recursively finds directories containing `SKILL.md` or `skill.md`. The entrypoint must contain simple YAML front matter with non-empty `name` and `description` fields:
+
+```markdown
+---
+name: release-review
+description: Review a release without publishing it.
+---
+
+# Workflow
+
+...
+```
+
+Invalid skills are skipped and reported in `skill_warnings` or `warnings`; one malformed bundle does not prevent valid skills from loading.
+
+Symlinked skill folders are followed, matching Codex behavior. Under workspace-confined profiles, the canonical symlink target must remain inside the workspace. Skill entrypoint files themselves may not be symbolic links. Directory traversal, cycles, entry count, depth, content, and returned file inventory are bounded.
+
+## Progressive disclosure
+
+`agent_context` initially returns only skill metadata: name, description, path, ID, size, and hash. Its skill summary list has an 8,000-character budget and a caller-selected count limit. Descriptions are shortened first and excess skills are omitted with `skills_truncated: true`.
+
+`load_local_skill` accepts a stable opaque ID, an unambiguous exact name, or a displayed entrypoint path. It returns:
+
+- the full bounded UTF-8 `SKILL.md` content;
+- metadata and a content hash;
+- a bounded relative inventory of files in the skill directory.
+
+Loading a skill never executes its scripts. The model must inspect the instructions and then invoke an ordinary bridge tool, a registered command, or a managed job. This keeps documentation loading separate from executable authority.
+
+## Registered command execution
+
+`run_local_command` is available only when direct process execution is enabled (`agent` or `full`, including equivalent custom policies). It does not invoke a shell. Manifest `argv` elements and caller-supplied arguments remain distinct process arguments, so characters such as `;`, `$()`, pipes, and redirections are not interpreted by a shell.
+
+The manifest remains authoritative:
+
+- caller arguments are rejected unless `allow_extra_args` is true;
+- a caller can reduce the timeout but cannot increase it beyond `timeout_seconds`;
+- the working directory is canonicalized and remains subject to active path policy;
+- the command receives the isolated or full environment selected by the Machine Bridge profile.
+
+Registered commands are workflow aliases, not a sandbox or approval boundary. Repository-controlled package scripts, interpreters, compilers, and executables can run arbitrary code with the local user's authority. Use `edit` or `review`, or external VM/container isolation, for untrusted repositories.
+
+For arbitrary one-off execution, existing tools remain available according to policy:
+
+- `run_process` for direct argv execution;
+- `exec_command` for shell syntax under shell-enabled policy;
+- `start_job` for durable multi-step work;
+- `stage_job` for local operator review and later approval.
+
+## Recommended remote workflow
+
+A remote coding task should normally follow this sequence:
+
+1. call `agent_context` with the file or directory being changed;
+2. apply returned instructions in precedence order;
+3. load only skills relevant to the task;
+4. inspect files before editing;
+5. prefer a registered command for validation or a standard workflow;
+6. use direct or shell execution only when the registry does not cover the operation;
+7. report files changed and commands run.
+
+This approximates local coding-agent context loading while keeping MCP transport, local policy, and host policy as explicit independent boundaries.
+
+## Security and failure behavior
+
+Agent configuration, instruction content, skill traversal, skill summaries, skill inventory, command count, argv size, timeouts, and process output are bounded. Invalid JSON, unknown fields, escaping paths, ambiguous skill names, invalid skill metadata, and missing commands fail explicitly or produce bounded warnings.
+
+Instruction and skill contents are untrusted operational text. They may contain prompt injection or unsafe command guidance. Machine Bridge exposes the content; it does not certify or approve it.

package/docs/ARCHITECTURE.md

@@ -32,12 +32,21 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 - process-session buffers and stdin lifecycle;
 - layered fixed runtime diagnostics;
 - local resource aliases and detached managed-job coordination;
+- agent-context discovery and registered-command execution coordination;
 - mutation serialization;
 - child-process tracking and cancellation;
 - output, traversal, concurrency, and time limits.
 
 `RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
 
+### Agent context manager
+
+`AgentContextManager` is a local domain module beneath `LocalRuntime`. It discovers the nearest Git/workspace scope, applies optional user configuration and hierarchical `.machine-bridge/agent.json` files, selects the first non-empty instruction candidate in each global/root-to-target scope, discovers bounded Codex-style `.agents/skills` metadata, and resolves registered commands. The runtime remains responsible for canonical path policy and process execution.
+
+The MCP surface is deliberately static: `agent_context`, `list_local_skills`, `load_local_skill`, `list_local_commands`, and `run_local_command`. Skills and commands do not become dynamically named MCP tools. This avoids host-side catalog caching/filtering problems and keeps one schema contract across Worker and stdio transports. Initial skill delivery is metadata-only and budgeted; loading a skill is read-only and execution requires a separate ordinary tool call. Registered commands use direct argv spawning and inherit the active runtime environment policy.
+
+See [Agent context, local skills, and registered commands](AGENT_CONTEXT.md) for precedence and configuration semantics.
+
 ### Managed job runner
 
 `ManagedJobManager` persists bounded per-workspace job envelopes below the owner-only profile directory. `start_job` validates the complete plan, snapshots referenced resource metadata/hashes, writes an owner-only plan/status, and launches `job-runner.mjs` as a detached process with runner-level logs redirected to owner-only files. `stage_job` performs the same acceptance validation but writes a non-running `staged` envelope; only local `job approve` transitions it to queued and launches the runner.
@@ -177,11 +186,11 @@ Managed jobs use the same argv/environment primitives but a different lifecycle.
 
 ## Daemon reconnect and replacement
 
-The local `RelayConnection` treats transport open, authenticated readiness, and outage recovery as separate states. It sends `hello` after WebSocket open and reports readiness only after `hello_ack`. A missing acknowledgement reaches a local handshake deadline and the candidate is terminated. Once ready, application heartbeats require inbound activity; a silent half-open socket is terminated and reconnected.
+The local `RelayConnection` treats transport construction, transport open, authenticated readiness, and outage recovery as separate states. A connection-attempt deadline terminates sockets stuck in `CONNECTING`; after WebSocket open it sends `hello` and reports readiness only after `hello_ack`. A missing acknowledgement reaches a distinct handshake deadline and the candidate is terminated. Once ready, application heartbeats require inbound activity; a silent half-open socket is terminated and reconnected. Outage reminders run on their own exponential-backoff timer rather than depending on another transport callback.
 
 Reconnect uses bounded exponential backoff with jitter. Brief self-healing interruptions are debug-only. An unresolved outage is promoted to a rate-limited warning after a grace period, and recovery produces one summary. Raw close codes and reason strings remain debug-only.
 
-The Worker also treats a new connection as a bounded candidate until it authenticates and completes `hello`; a Durable Object alarm enforces the deadline across hibernation. Only a completed candidate replaces the old socket. Pending calls retain their originating socket reference. A stale socket cannot complete or cancel replacement-socket calls. Closing a socket rejects only calls assigned to it.
+The Worker also treats a new connection as a bounded candidate until it authenticates and completes `hello`; a Durable Object alarm enforces the deadline across hibernation. Only a completed candidate replaces the old socket. Daemon messages must be valid JSON objects, duplicate `hello` and unknown message types are rejected with explicit protocol errors, and protocol violations close with standard WebSocket status codes. Pending calls retain their originating socket reference. A stale socket cannot complete or cancel replacement-socket calls. Closing a socket rejects only calls assigned to it.
 
 ## Persistence
 

package/docs/ENGINEERING.md

@@ -13,6 +13,12 @@ This document records project-wide decisions that must survive individual fixes,
 
 A proposed change that conflicts with an invariant requires an explicit owner decision and corresponding documentation update. It must not be hidden inside an unrelated refactor.
 
+## Change and release-operation ownership
+
+Repository changes and live release operations are separate responsibilities. Unless the current task explicitly authorizes a broader scope, coding automation may edit source, tests, documentation, package metadata, and changelog entries; run repository-local checks; commit; and push to GitHub. It must not publish or alter npm releases, create tags or GitHub Releases, install the package globally, deploy or reconfigure a Cloudflare Worker, rotate credentials, mutate live deployment state, or start/stop/install/remove the daemon or autostart service.
+
+The normal handoff is: the repository owner publishes the reviewed npm version, then runs `npm install -g --allow-scripts=esbuild,workerd,sharp machine-bridge-mcp@latest && machine-mcp`. The npm command updates the global CLI. The subsequent normal startup validates the Worker deployment hash, expected version, and health, redeploys when necessary, and reconciles the daemon/autostart flow. Live operations require explicit authorization even when they appear to be the obvious next release step.
+
 ## Architectural boundaries
 
 The preferred dependency direction is:

package/docs/LOGGING.md

@@ -41,10 +41,12 @@ Brief network interruptions are expected on laptop network changes, Worker deplo
 
 - the raw close code, close reason, error class, connected duration, and retry delay are debug-only;
 - a brief interruption that reconnects within the grace period produces no `info` or `warn` line;
-- an outage that remains unresolved for 10 seconds produces one rate-limited warning stating that automatic reconnection is in progress;
-- relay identity/version mismatch and authentication rejection are non-transient: they produce an immediate actionable error and terminate that daemon instead of entering the reconnect loop;
-- repeated warnings are rate-limited;
-- recovery after a visible outage produces one information summary with outage duration and attempt count;
+- an outage that remains unresolved for 10 seconds produces a user-readable warning stating the duration, reconnect attempt count, classified cause, and automatic recovery behavior;
+- while the outage remains unresolved, reminders are scheduled independently of reconnect callbacks and use exponential backoff capped at 15 minutes;
+- a WebSocket that remains in `CONNECTING` beyond its deadline is terminated so one stalled network attempt cannot freeze the reconnect loop;
+- relay identity/version mismatch, authentication rejection, and unexpected protocol messages are non-transient: they produce an immediate actionable error and terminate that daemon instead of entering the reconnect loop;
+- a Worker `daemon_hello_timeout` error is transient and follows the normal reconnect path rather than being misclassified as authentication rejection;
+- recovery after a visible outage produces one information summary with a human-readable duration and attempt count; exact seconds and error classes remain debug-only;
 - an authenticated replacement is a distinct warning and permanently stops the older daemon;
 - failure to receive `hello_ack` within the handshake deadline terminates the candidate socket and retries;
 - lack of inbound heartbeat activity terminates a half-open socket and reconnects.
@@ -55,11 +57,11 @@ Examples:
 
 ```text
 [info] daemon: remote relay connected
-[warn] daemon: remote relay is unavailable; automatic reconnection is still in progress {"outage_seconds":12,"attempts":3,"cause":"connection interrupted"}
-[info] daemon: remote relay connection restored {"outage_seconds":18,"attempts":4}
+[warn] daemon: remote relay unavailable for 12 seconds; reconnecting automatically (3 reconnect attempts; connection interrupted).
+[info] daemon: remote relay connection restored after 18 seconds (4 reconnect attempts)
 ```
 
-With `--verbose`, the same incident may additionally include bounded transport diagnostics.
+With `--verbose`, the same incident additionally includes bounded structured fields such as exact seconds, coarse error class, retry delay, and transport close diagnostics.
 
 ## Tool events
 

package/docs/OPERATIONS.md

@@ -26,19 +26,19 @@ A successful diagnostic result applies only to that probe. An MCP host can still
 
 ### Relay interruption messages
 
-A brief relay interruption is retried automatically and is visible only with `--verbose`. Default logs do not print raw WebSocket values such as `code=1006` with an empty reason. If a transient outage persists for 10 seconds, one warning is emitted and repeated warnings are rate-limited; a later recovery produces one summary with outage duration and attempt count. Identity/version mismatch and authentication rejection are not retried as ordinary network faults: the daemon emits an immediate actionable error and exits, requiring upgrade/redeployment or credential repair.
+A brief relay interruption is retried automatically and is visible only with `--verbose`. Default logs do not print raw WebSocket values such as `code=1006` with an empty reason. If a transient outage persists for 10 seconds, the daemon emits a readable duration/cause/reconnect summary; later reminders use autonomous exponential backoff capped at 15 minutes, and recovery produces one readable summary. Each transport connection attempt also has a deadline, so a socket stuck in `CONNECTING` cannot freeze retries. Identity/version mismatch, authentication rejection, and unexpected protocol messages are not retried as ordinary network faults: the daemon emits an immediate actionable error and exits, requiring upgrade/redeployment or credential repair. A Worker-side daemon handshake timeout remains retryable.
 
 Use `--verbose` only when close codes, close reasons, heartbeat timeouts, and retry delays are needed for diagnosis. A close code of 1006 means the transport ended without a normal close handshake; it does not by itself identify the cause.
 
 ## Logs
 
-Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
+Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.
 
 Logging is level-based:
 
 ```text
 error  unrecoverable local/transport/service failures
-warn   relay disconnect/send failures, malformed relay events, supersession and service problems
+warn   persistent retryable relay degradation, supersession, and service problems
 info   startup/deploy/connect transitions
 debug  all per-tool starts/successes/failures/cancellations/timing, correlation and reconnect details
 ```

package/docs/TESTING.md

@@ -13,9 +13,11 @@ The repository requires Node.js 26 and npm 12. `.node-version`, `.nvmrc`, `packa
 The suite includes:
 
 - release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
-- generated Cloudflare Worker types and strict TypeScript checking;
+- release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, including the required publication order;
+- generated Cloudflare Worker types and strict TypeScript checking, including unused-local and unused-parameter rejection;
 - syntax validation for every shipped JavaScript entry point;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
+- hierarchical agent-context precedence, custom instruction ordering, local skill discovery/loading, command override/removal, direct argv argument handling, timeout ceilings, and execution-profile denial;
 - canonical path and symbolic-link escape tests;
 - relative-path privacy and error-path redaction tests;
 - atomic create/update, optimistic hash, exact edit, and patch transaction tests;
@@ -37,11 +39,11 @@ The suite includes:
 - guarded state-root removal, schema migration, policy-origin persistence, and legacy implicit-default migration;
 - no filename-based sensitive-file denial under unrestricted policy;
 - log redaction, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, service warning-level configuration, and idempotent bounded migration of legacy log formats;
-- deterministic relay connection lifecycle coverage for transport construction/error, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, handshake and heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
+- deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, retryable Worker handshake errors, fatal protocol errors, autonomous outage-reminder backoff, handshake and heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
 - shared no-follow bounded-file reads for normal files, over-limit data, directories, and symbolic links;
 - CLI parsing, policy profiles, and client configuration boundaries;
 - live stdio MCP initialization, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
-- live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, and cancellation.
+- live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure.
 
 ## Additional release checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Cross-client MCP bridge for canonical local automation, files, Git, SSH resources, managed jobs, and processes over stdio or an OAuth-protected remote relay.",
   "type": "module",
   "license": "MIT",
@@ -43,8 +43,8 @@
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
     "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
-    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
+    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs",
+    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run agent-context:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -65,7 +65,9 @@
     "relay:test": "node tests/relay-connection-test.mjs",
     "install:test": "node tests/install-smoke-test.mjs",
     "secure-file:test": "node tests/secure-file-test.mjs",
-    "architecture:test": "node tests/architecture-test.mjs"
+    "architecture:test": "node tests/architecture-test.mjs",
+    "release-state:test": "node tests/release-state-test.mjs",
+    "agent-context:test": "node tests/agent-context-test.mjs"
   },
   "dependencies": {
     "wrangler": "4.110.0",