machine-bridge-mcp 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.11.1 - 2026-07-12
+
+### Reliable macOS service and orphan-daemon takeover
+
+- Stop launchd jobs by their loaded service target first, with the plist form retained as a compatibility fallback. Treat an already-unloaded job as an idempotent success, verify the post-stop state before reporting success, and prevent `service start` or `service uninstall` from continuing when the existing job remains active.
+- Detect legacy daemon locks that predate mode/version metadata by inspecting the live process command line. A process is eligible for takeover only when its PID, daemon purpose, canonical workspace, canonical state root, entrypoint, and `--daemon-only` arguments all match. Foreground or unverifiable processes are never signalled.
+- Let normal foreground startup and `machine-mcp service stop` terminate a verified detached/orphan service daemon with `SIGTERM`, wait for the actual PID as well as the lock to disappear, reclaim stale locks through the normal token-aware primitive, and fail with a bounded timeout rather than escalating to a forced kill.
+- Extend `machine-mcp service status` to report platform-service state and workspace-daemon state separately, including whether a live legacy process was verified as service-style. This makes a launchd-unloaded but still-running daemon visible instead of presenting a misleading inactive-only status.
+
+### Tests and documentation
+
+- Add real child-process regression coverage for legacy orphan takeover, canonical `/var` versus `/private/var` path aliases, foreground-process protection, non-forcing timeout behavior, launchd service-target generation, and packaged daemon-process module presence. Update upgrade and recovery guidance for the exact npm install command and split service/daemon diagnosis.
+
+## 0.11.0 - 2026-07-12
+
+### Zero-configuration agent working agreements
+
+- Add a package-controlled `machine-bridge://defaults/working-agreements` instruction layer so every stdio and remote MCP session starts with conservative, auditable guidance even when the user and repository provide no `MODEL.md`, `AGENTS.md`, or manifest. The baseline covers inspect-before-editing, minimal coherent changes, preservation of unrelated work, existing-toolchain reuse, tests/documentation synchronization, honest validation reporting, secret handling, safe Git practice, and explicit authorization for publication, deployment, credential rotation, live-data mutation, system-wide installation, and destructive operations.
+- Keep the baseline lower precedence than explicit user and root-to-target project instructions. Expose its source, size, hash, precedence, and optional content through `session_bootstrap`, `agent_context`, and `resolve_task_capabilities`; include its hash in live capability fingerprints. The defaults are behavioral guidance rather than a replacement for Machine Bridge policy, host approvals, operating-system permissions, hooks, sandboxes, or external isolation.
+
+### Bounded automatic project context
+
+- Add `machine-bridge://project-context/current`, regenerated on every relevant context scan from bounded repository metadata: target-relative path, recognized project/build entry files, JavaScript package-manager and lockfile facts, package script names, runtime constraints/version hints, common documentation files, and CI entrypoint filenames. The scanner executes nothing, writes no user or repository files, omits script bodies, dependency values, source/document contents, absolute home paths, and command output, and never claims a declared command was validated.
+- Harden repository-controlled metadata with strict character/count/byte limits, no-follow regular-file reads, safe workflow-name filtering, independent 16 KiB output bounds, and conservative skipping of symbolic links, invalid UTF-8, oversized files, permission failures, and transient metadata races. Add user-global `builtin_instructions` and `automatic_project_context` boolean opt-outs; project manifests cannot disable the user's baseline controls.
+
+### Documentation and verification
+
+- Document the default instruction model, precedence, opt-outs, privacy data surface, security boundary, recommended `AGENTS.md` content, progressive disclosure, and official cross-agent best-practice sources. Update repository automation guidance, shared MCP tool descriptions, initialization instructions, architecture, clients, logging, privacy, security, testing, and package contents.
+- Add regression coverage for no-file defaults, initialization injection over stdio, automatic project refresh/fingerprints, package-manager/lockfile/script/CI discovery, script-body non-disclosure, hostile metadata filtering, global opt-out, project opt-out rejection, precedence, and packaged-module presence.
+
+## 0.10.1 - 2026-07-12
+
+### Foreground startup and upgrade takeover
+
+- Make a normal `machine-mcp` start reliably take over from an active platform autostart daemon: detect whether the service is active, request shutdown, wait up to 15 seconds for the workspace daemon lock to be released, and then continue foreground startup with the newly installed CLI. A failed bounded takeover now exits with explicit `service stop`/`service status` recovery guidance instead of silently leaving the old process in place.
+- Record foreground/background mode and package version in new daemon locks. A genuine lock conflict now identifies the running mode/version when known, explains how to stop it, and no longer prints the misleading `[ok] ready` block when no restart or requested change occurred. Service-style duplicate starts remain silent idempotent successes.
+
+### Global instructions and operator guidance
+
+- Add copy-paste setup instructions for `~/.config/machine-bridge-mcp/agent.json` and the global `MODEL.md`, explain global-versus-project precedence, live rescanning, and when a new MCP conversation/reconnection is needed for initialization-time injection.
+- Document the foreground/background distinction, safe global upgrade sequence, owner-only instruction-file permissions, background log locations, and the exact optional-dependency install command that avoids the development-only `fsevents` warning.
+
 ## 0.10.0 - 2026-07-12
 
 ### Session context and capability selection

package/README.md

@@ -51,7 +51,7 @@ Node.js 26 or newer and npm 12 or newer are required. The repository pins the ac
 npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
 ```
 
-Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command approves the reviewed native script names that npm 12 evaluates during global resolution while `--omit=optional` keeps optional `fsevents` out of the installed runtime. `fsevents` is used for development-time filesystem watching rather than Machine Bridge runtime or deployment. It does not change the user's global npm policy. `machine-mcp doctor` remains the authoritative runtime check.
+Recent npm releases may otherwise warn that Wrangler's native dependencies (`esbuild`, `workerd`, and `sharp`) have install scripts awaiting approval. The scoped command approves the reviewed native script names that npm 12 evaluates during global resolution while `--omit=optional` keeps optional `fsevents` out of the installed runtime. `fsevents` is used for development-time filesystem watching rather than Machine Bridge runtime or deployment. Omitting `--omit=optional` can therefore produce a harmless blocked-script warning for `fsevents@2.3.3`; use the documented command rather than changing global npm policy. `machine-mcp doctor` remains the authoritative runtime check.
 
 From a source checkout, the checked-in exact-version `allowScripts` policy approves the reviewed native dependencies:
 
@@ -79,6 +79,17 @@ On first remote start, the CLI:
 6. starts an outbound-only daemon connection;
 7. prints the Remote MCP URL and connection password.
 
+A normal `machine-mcp` invocation is a foreground start: it remains attached to the terminal and prints `info` logs. After a global package upgrade, the CLI unloads the platform service and also checks the workspace lock for a detached/orphan `--daemon-only` process that the service manager no longer tracks. It terminates only a process whose PID, entrypoint, canonical workspace, canonical state root, and daemon-only arguments all match, waits up to 15 seconds for the PID and lock to disappear, and then starts the installed version in the foreground. A genuine foreground or unverifiable conflict is left untouched and reported with actionable guidance. To run only in the background, use `machine-mcp service start`; inspect its owner-only logs under `~/.local/state/machine-bridge-mcp/logs/`.
+
+Recommended upgrade sequence:
+
+```sh
+npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+machine-mcp --verbose
+```
+
+The global install replaces files on disk but cannot hot-reload an already running Node process; the second command performs the bounded service and orphan-daemon takeover. Use the command exactly as shown: `--omit=optional` prevents the development-only optional `fsevents` package from producing a blocked-install-script warning. If takeover fails, run `machine-mcp service status` first; it reports the platform service and workspace daemon separately. Then run `machine-mcp service stop` and retry.
+
 Use the printed values in the MCP client:
 
 ```text
@@ -110,7 +121,16 @@ The stdio server writes only JSON-RPC messages to stdout and operational logs to
 
 ## Session instructions, local skills, commands, apps, and browser
 
-Machine Bridge loads a user-selected global instruction file and repository-specific guidance without changing the static MCP catalog. Configure the global file in `~/.config/machine-bridge-mcp/agent.json`:
+Machine Bridge now starts with useful agent guidance even when the user has not created `MODEL.md`, `AGENTS.md`, or `.machine-bridge/agent.json`.
+
+Two lower-precedence virtual sources are generated in memory:
+
+- `machine-bridge://defaults/working-agreements` supplies conservative cross-project rules for inspection, scoped changes, preservation of unrelated work, validation, security, Git discipline, and explicit authorization for deployment/publication/destructive operations.
+- `machine-bridge://project-context/current` derives bounded facts from the active repository: target path, common project/build files, package-manager declarations and lockfiles, package script names, runtime constraints, documentation files, and CI entrypoints. It never injects package-script bodies or source contents and does not claim commands were validated.
+
+No files are created or modified by this bootstrap. Explicit user and repository instructions load later and therefore override the defaults. `session_bootstrap` supplies the chain during MCP initialization; `agent_context` exposes every source and hash; `resolve_task_capabilities` refreshes project facts, instructions, skills, and commands for the current task.
+
+Optional user-global preferences still live in `~/.config/machine-bridge-mcp/agent.json`:
 
 ```json
 {
@@ -119,9 +139,21 @@ Machine Bridge loads a user-selected global instruction file and repository-spec
 }
 ```
 
-The file is prepended to MCP initialization instructions for every new stdio or remote session when the local runtime is reachable. `session_bootstrap` exposes the same material explicitly. `agent_context` adds target-specific `AGENTS.override.md`/`AGENTS.md` precedence, and `resolve_task_capabilities` rescans skills and registered commands for the current task, ranks matches, optionally loads the best skill, and recommends relevant local tools.
+Use `MODEL.md` for preferences not covered by the baseline, such as default language or organization-specific review rules. Repository-specific rules belong in `AGENTS.md`/`AGENTS.override.md`; deeper files take precedence. Keep secrets out of every instruction file.
+
+To disable either automatic layer globally:
+
+```json
+{
+  "version": 1,
+  "builtin_instructions": false,
+  "automatic_project_context": false
+}
+```
+
+Repositories cannot disable these user-level controls. Editing instruction files or project metadata does not require a daemon restart; start a new MCP conversation or reconnect when initialization-time injection must be guaranteed from the beginning.
 
-Skill discovery follows Codex-style progressive disclosure. Default roots are target-to-project `.agents/skills`; unrestricted policy also enables user/admin roots. Newly added or edited skills are found on the next resolver/list call without restarting the daemon. A project can customize instruction candidates, skill roots, and direct-argv registered commands with `.machine-bridge/agent.json`. See [Session instructions, skills, commands, and capability discovery](docs/AGENT_CONTEXT.md).
+Skill discovery follows Codex-style progressive disclosure. Default roots are target-to-project `.agents/skills`; unrestricted policy also enables user/admin roots. Newly added or edited skills are found on the next resolver/list call without restarting the daemon. A project can customize instruction candidates, skill roots, and direct-argv registered commands with `.machine-bridge/agent.json`. See [Session instructions, defaults, skills, commands, and capability discovery](docs/AGENT_CONTEXT.md).
 
 Under canonical `full`, Machine Bridge also exposes structured local automation:
 
@@ -265,8 +297,8 @@ The exact `tools/list` response reflects the active local policy. Definitions co
 
 - `server_info`
 - `project_overview`
-- `session_bootstrap` — session/global instructions and capability refresh metadata
-- `agent_context` — effective instructions, skill summaries, and registered commands for a target path
+- `session_bootstrap` — built-in defaults, automatic project facts, explicit instructions, and refresh metadata
+- `agent_context` — complete default/explicit instruction precedence, skill summaries, and registered commands for a target path
 - `resolve_task_capabilities` — live skill/command ranking and local automation recommendations
 - `list_local_skills`
 - `load_local_skill` — load instructions and file inventory without implicit execution

package/SECURITY.md

@@ -53,7 +53,9 @@ For untrusted repositories or instructions, run the bridge inside a disposable V
 
 ## 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.
+Machine Bridge prepends a package-controlled built-in working-agreement block and an optional bounded automatic project-context block before repository/user instructions. The built-in block is guidance, not a security boundary. Automatic context reads only recognized root filenames, package-manager/lockfile facts, package script names, runtime constraints, common documentation names, and CI filenames; it does not inject script bodies, dependency values, source contents, or execute discovered commands. Symbolic-link, oversized, invalid-UTF-8, and unsupported metadata is skipped conservatively.
+
+Repository and user instruction files remain 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, filename, script name, or `SKILL.md` can attempt prompt injection or recommend destructive operations. Use only trusted repositories and skill roots, keep host approvals/policy enabled, 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.
 
@@ -61,7 +63,7 @@ Registered commands are available only under direct-execution-capable policy. Th
 
 The remote MCP host remains an independent boundary. Machine Bridge can advertise these tools, append `model_instructions_file` during initialization, and recommend capabilities through `resolve_task_capabilities`, but it cannot force a host to preserve instructions, expose tools, approve calls, or invoke them.
 
-The global `model_instructions_file` is an explicit user trust decision. It is read for every profile and sent to the authorized host during session initialization; do not place credentials, private records, or content inappropriate for every connected session in it. Project manifests cannot override this global file. Other global manifest fields that would widen local scope are ignored under workspace-confined profiles.
+The global `model_instructions_file` is an explicit user trust decision. It is read for every profile and sent to the authorized host during session initialization; do not place credentials, private records, or content inappropriate for every connected session in it. Project manifests cannot override this global file or the global `builtin_instructions`/`automatic_project_context` controls. Other global manifest fields that would widen local scope are ignored under workspace-confined profiles.
 
 ## Browser and application automation
 

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -29,5 +29,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.10.0"
+  "version_name": "0.11.1"
 }

package/docs/AGENT_CONTEXT.md

@@ -1,14 +1,14 @@
-# Session instructions, skills, commands, and capability discovery
+# Session instructions, defaults, skills, commands, and capability discovery
 
-Machine Bridge provides a static MCP bootstrap surface for Codex-style instructions and filesystem skills. The catalog remains stable while local instructions, skills, commands, applications, and browser state are discovered at call time.
+Machine Bridge provides a static MCP bootstrap surface with useful working agreements even when the user and repository have no instruction files. The catalog remains stable while default project facts, explicit instructions, skills, commands, applications, and browser state are discovered at call time.
 
 This approximates a local coding agent without pretending that the MCP server owns the model loop. The host can filter tools, require confirmation, truncate context, or decline calls before they reach Machine Bridge.
 
 ## MCP tools
 
-- `session_bootstrap` returns the current global/session instruction text and refresh fingerprint.
+- `session_bootstrap` returns built-in working agreements, bounded automatic project facts, explicit instruction text, and a refresh fingerprint.
 - `agent_context` returns the complete target-specific instruction chain, skill summaries, and command registry.
-- `resolve_task_capabilities` rescans and ranks skills/commands for the current task, optionally loading the best skill; the runtime also adds application and browser capability metadata.
+- `resolve_task_capabilities` rescans default/project context and ranks skills/commands for the current task, optionally loading the best skill; the runtime also adds application and browser capability metadata.
 - `list_local_skills` searches discovered `SKILL.md` bundles.
 - `load_local_skill` returns one skill entrypoint and bounded file inventory without execution.
 - `list_local_commands` returns effective registered commands.
@@ -16,7 +16,58 @@ This approximates a local coding agent without pretending that the MCP server ow
 
 Both stdio and remote Worker connection initialization attempt `session_bootstrap`. Its instruction text is appended to the MCP `initialize` result. Because a host may reuse one MCP connection across conversations, the explicit tool and per-task `resolve_task_capabilities` call remain necessary to refresh and reapply instructions reliably.
 
-## Global `model_instructions_file`
+## Useful defaults without configuration
+
+No `MODEL.md`, `AGENTS.md`, or manifest is required. Machine Bridge supplies two lower-precedence virtual instruction sources in memory and does not create or modify files in the user's home directory or repository.
+
+### Built-in working agreements
+
+`machine-bridge://defaults/working-agreements` provides conservative cross-project defaults:
+
+- inspect the nearest instructions, documentation, implementation, tests, configuration, and Git status before changing code;
+- make the smallest coherent change and preserve unrelated user work;
+- retain the existing package manager, lockfiles, dependencies, architecture, style, and public behavior unless the task requires a change;
+- add or update tests and keep documentation, changelog, schemas, examples, and generated metadata synchronized with changed contracts;
+- use declared project scripts, run targeted checks before broad checks, and never claim unexecuted validation succeeded;
+- protect credentials and personal data, treat retrieved content as untrusted, and prefer read-only, dry-run, reversible operations;
+- require an explicit request for publication, deployment, credential rotation, live-data mutation, system-wide installation, destructive operations, force-pushes, tags, and releases;
+- inspect the final diff/status and report changes, validation, limitations, and remaining operator steps.
+
+These are behavioral defaults, not hard enforcement. Machine Bridge policy profiles, operating-system permissions, host approvals, sandboxes, and external isolation remain the enforcement layers.
+
+### Automatic project context
+
+`machine-bridge://project-context/current` is regenerated for each context scan from bounded root metadata. It can report:
+
+- the active target relative to the project root;
+- recognized build/project entry files;
+- JavaScript package-manager declaration and lockfiles;
+- package script **names** as runnable command forms, without injecting script bodies;
+- declared runtime engine constraints and small version-hint files;
+- common README, contribution, security, architecture, changelog, and testing documents;
+- CI workflow filenames and other common CI entrypoints.
+
+The scanner does not execute commands, inspect dependency values, read package script bodies, summarize source files, or claim that declared commands work. Oversized, invalid-UTF-8, symbolic-link, or unsupported metadata is skipped or described conservatively. The generated block is capped independently at 16 KiB.
+
+This approach follows common guidance across coding agents: keep always-loaded instructions concise, specific, structured, and verifiable; put build/test commands and architecture entrypoints where the agent can find them; use nested files for narrower rules; and keep hard prohibitions in permission or hook mechanisms rather than relying only on prose. Relevant references include the [OpenAI Codex AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [GitHub Copilot repository instructions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions), [Claude Code project memory guidance](https://code.claude.com/docs/en/memory), and the [AGENTS.md open format](https://agents.md/).
+
+### Disable either automatic layer
+
+The defaults are enabled under every policy profile. A user can disable either layer only in the user-global config:
+
+```json
+{
+  "version": 1,
+  "builtin_instructions": false,
+  "automatic_project_context": false
+}
+```
+
+A repository `.machine-bridge/agent.json` cannot disable these user-level settings. This prevents a repository from silently removing the user's baseline working agreements. Disabling automatic project context also prevents its bounded metadata from traversing a remote Worker/host.
+
+## Optional global `model_instructions_file`
+
+Use a user-authored global file only for preferences not covered by the built-in baseline, such as language, preferred explanation depth, organization-specific review rules, or personal tooling conventions.
 
 The user-level configuration is:
 
@@ -33,13 +84,34 @@ Example:
 }
 ```
 
-The file is loaded before repository guidance for every session and every target path. It must be a non-empty, regular, non-symbolic-link UTF-8 file and is bounded by the hard instruction-file limit. Relative values are resolved from the user's home directory.
+Copy-paste setup on macOS/Linux:
 
-`model_instructions_file` is global-only. A project `.machine-bridge/agent.json` cannot set or override it. It is read even under workspace-confined profiles because the user explicitly designated it as session configuration. Under those profiles, other user-manifest fields that would widen filesystem/skill/command scope are ignored; project instruction and command policy remains confined.
+```sh
+mkdir -p ~/.config/machine-bridge-mcp
+cat > ~/.config/machine-bridge-mcp/MODEL.md <<'PROMPT'
+# Personal preferences
 
-In remote mode, the selected instruction text necessarily traverses the user's Cloudflare Worker and the authorized MCP host as part of initialization. Do not put credentials or private data in an instruction file.
+- Respond in Chinese unless I request another language.
+- Explain non-obvious architectural decisions and report validation results.
+PROMPT
+cat > ~/.config/machine-bridge-mcp/agent.json <<'JSON'
+{
+  "version": 1,
+  "model_instructions_file": "~/.config/machine-bridge-mcp/MODEL.md"
+}
+JSON
+chmod 600 ~/.config/machine-bridge-mcp/agent.json ~/.config/machine-bridge-mcp/MODEL.md
+```
+
+The file must be a non-empty, regular, non-symbolic-link UTF-8 file and is bounded by the hard instruction-file limit. Relative values are resolved from the user's home directory. Keep credentials, tokens, private keys, and unrelated personal data out of instruction files.
+
+Changes are discovered on the next `session_bootstrap`, `agent_context`, or `resolve_task_capabilities` call and do not require daemon restart. Because an MCP host may reuse a connection and may not call those tools automatically, start a new conversation or reconnect the MCP client when revised global instructions must be present in initialization context from the beginning.
 
-## Repository instruction precedence
+`model_instructions_file`, `builtin_instructions`, and `automatic_project_context` are global-only. Project manifests cannot set or override them. The global model file and the two boolean controls are honored under workspace-confined profiles; other user-manifest fields that would widen filesystem/skill/command scope remain ignored there.
+
+In remote mode, the selected instruction text and enabled automatic project facts necessarily traverse the user's Cloudflare Worker and authorized MCP host as part of initialization. Do not put credentials or private records in instructions.
+
+## Instruction precedence
 
 For a target path, Machine Bridge chooses the nearest Git ancestor as scope root, falling back to the configured workspace or target directory. The default candidate priority in each directory is:
 
@@ -50,14 +122,16 @@ For a target path, Machine Bridge chooses the nearest Git ancestor as scope root
 ]
 ```
 
-Order:
+Effective order, from lowest to highest precedence:
 
-1. `model_instructions_file`, when configured;
-2. under unrestricted policy, the first non-empty candidate in `CODEX_HOME` or `~/.codex`;
-3. project scope root through the target directory;
-4. in each directory, apply `.machine-bridge/agent.json`, then select its first non-empty candidate.
+1. built-in working agreements, unless globally disabled;
+2. automatic project context, when enabled and relevant metadata exists;
+3. `model_instructions_file`, when configured;
+4. under unrestricted policy, the first non-empty candidate in `CODEX_HOME` or `~/.codex`;
+5. project scope root through the target directory;
+6. in each directory, apply `.machine-bridge/agent.json`, then select its first non-empty candidate.
 
-Only one candidate contributes per directory. Deeper files have higher precedence. Empty files are skipped. The repository/global candidate budget defaults to 32 KiB and can be configured up to the hard 2 MiB ceiling. The separately designated model-instructions file retains its own file-size ceiling.
+Only one explicit candidate contributes per directory. Deeper files have higher precedence. Empty files are skipped. The repository/global candidate budget defaults to 32 KiB and can be configured up to the hard 2 MiB ceiling. The built-in baseline, automatic context, and separately designated model file retain independent bounds.
 
 ## Project manifest
 
@@ -90,6 +164,8 @@ A project manifest lives at `.machine-bridge/agent.json`:
 
 Supported project fields are `version`, `instruction_files`, `instruction_max_bytes`, `skill_roots`, and `commands`. Unknown fields fail closed. Deeper manifests replace inherited instruction/skill settings, override commands by name, and can delete a command with `null`.
 
+Use `AGENTS.md` for durable facts a new contributor or agent must know: validated setup/build/test commands, major architectural paths, code conventions, security constraints, and contribution/release rules. Keep it concise and concrete. Put specialized rules near the relevant subtree, and move multi-step task workflows into skills or registered commands rather than loading them into every session.
+
 ## Skill discovery and live refresh
 
 Without explicit `skill_roots`, discovery scans:
@@ -109,7 +185,7 @@ description: Review a release without publishing it.
 
 The entrypoint requires non-empty `name` and `description`. Invalid bundles are skipped with bounded warnings. Symlinked skill directories are followed after canonical policy validation; symbolic-link entrypoint files are rejected. Traversal, depth, entries, summaries, content, and inventory are bounded.
 
-No persistent skill index is trusted as authoritative. `agent_context`, `list_local_skills`, and `resolve_task_capabilities` rescan the effective roots. A refresh fingerprint changes when instruction hashes, skill hashes, command definitions, or relevant configuration changes. Newly created or edited skills are therefore visible without restarting the daemon or changing the MCP tool catalog.
+No persistent skill or project-context index is trusted as authoritative. `session_bootstrap`, `agent_context`, and `resolve_task_capabilities` rebuild the relevant context; skill-list/load calls rescan effective roots. The refresh fingerprint changes when built-in/default context, explicit instruction hashes, skill hashes, command definitions, or relevant configuration changes. Newly created or edited files are visible without restarting the daemon or changing the MCP tool catalog.
 
 ## Progressive disclosure and task selection
 
@@ -125,9 +201,9 @@ Registered commands are workflow aliases, not an approval boundary or sandbox. P
 
 ## Recommended host workflow
 
-1. consume MCP initialization instructions;
+1. consume MCP initialization instructions, including the built-in baseline and automatic project facts;
 2. call `resolve_task_capabilities` with the complete user task and target path;
-3. apply returned global/project instructions;
+3. apply explicit global/project instructions over lower-precedence defaults;
 4. follow the selected skill only after checking relevance;
 5. prefer registered commands for stable workflows;
 6. use structured application/browser tools where applicable;
@@ -137,4 +213,4 @@ Machine Bridge can automatically discover, refresh, rank, and load capabilities.
 
 ## Security and failure behavior
 
-Instruction and skill text is untrusted operational content and may contain prompt injection or destructive guidance. The bridge exposes it but does not certify it. Paths, files, roots, counts, byte budgets, argv, timeouts, and result sizes are bounded. Escaping paths, ambiguous skill names, malformed metadata, invalid configuration, and missing commands fail explicitly or produce bounded warnings.
+Instruction and skill text is untrusted operational content and may contain prompt injection or destructive guidance. The bridge exposes it but does not certify it. Automatic project context is deliberately limited to low-risk bounded metadata and excludes script bodies, source contents, dependency values, and secrets, but filenames and script names can still reveal project structure. Paths, files, roots, counts, byte budgets, argv, timeouts, and result sizes are bounded. Escaping paths, ambiguous skill names, malformed metadata, invalid configuration, and missing commands fail explicitly or produce bounded warnings.

package/docs/ARCHITECTURE.md

@@ -40,11 +40,13 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 
 `RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
 
+`daemon-process.mjs` owns workspace-daemon inspection and takeover. It distinguishes platform service state from the lock-owning Node process, canonicalizes workspace/state paths before identity comparison, parses bounded process command lines without executing them, and sends `SIGTERM` only to a verified same-workspace `--daemon-only` process. CLI orchestration never treats a missing launchd/systemd job as proof that the process exited.
+
 ### Agent context and capability resolver
 
-`AgentContextManager` discovers the nearest Git/workspace scope, applies the user configuration and hierarchical `.machine-bridge/agent.json` files, selects global/root-to-target instructions, discovers bounded filesystem skills, and resolves registered commands. A global `model_instructions_file` is a separate user-designated session source and cannot be overridden by a project.
+`AgentContextManager` discovers the nearest Git/workspace scope, applies the user configuration and hierarchical `.machine-bridge/agent.json` files, selects built-in/user/root-to-target instructions, discovers bounded filesystem skills, and resolves registered commands. `default-instructions.mjs` supplies a versioned in-package working-agreement block and derives a small virtual project-context block from root filenames and bounded metadata. It reads package script names but not bodies, does not inspect dependency values or source contents, executes nothing, and writes no user/repository files. A global `model_instructions_file` is a separate user-designated session source and cannot be overridden by a project.
 
-`session_bootstrap` is requested during both stdio and remote MCP initialization. The Worker delegates this read to the connected daemon with a short bounded timeout; failure falls back to static server instructions rather than blocking initialization indefinitely. `resolve_task_capabilities` performs a fresh deterministic scan and ranks skill/command metadata for the current task. Application and browser capability metadata is added by `LocalRuntime`.
+`session_bootstrap` is requested during both stdio and remote MCP initialization. The Worker delegates this read to the connected daemon with a short bounded timeout; failure falls back to static server instructions rather than blocking initialization indefinitely. `resolve_task_capabilities` performs a fresh deterministic scan, rebuilds automatic project facts, and ranks skill/command metadata for the current task. Application and browser capability metadata is added by `LocalRuntime`.
 
 The MCP catalog remains static: local skills and commands do not become dynamically named tools. This avoids stale host catalog caches and keeps Worker/stdio schema parity. Progressive disclosure separates discovery, instruction loading, and execution authority. A refresh fingerprint is descriptive rather than a cache-validity guarantee.
 

package/docs/CLIENTS.md

@@ -54,7 +54,7 @@ The MCP specification defines stdio and Streamable HTTP as standard transports.
 
 ## Automatic capability selection
 
-MCP server instructions and `resolve_task_capabilities` give the host a current view of global/project instructions, skills, registered commands, applications, and browser capability. The resolver rescans rather than relying on a stale dynamic tool list and can return the best matching skill instructions in one call.
+MCP initialization and `resolve_task_capabilities` give the host a current view of conservative built-in working agreements, bounded project facts, explicit global/project instructions, skills, registered commands, applications, and browser capability. The resolver rescans rather than relying on a stale dynamic tool list and can return the best matching skill instructions in one call. No instruction file is required for the default layers, and no repository file is written automatically.
 
 The host still owns the agent loop. ChatGPT web may use the recommendation automatically, ask for confirmation, expose only part of the catalog, or ignore server instructions. No MCP implementation can guarantee automatic invocation from the server side. Machine Bridge models that limitation explicitly instead of treating a recommendation as execution.
 

package/docs/ENGINEERING.md

@@ -20,7 +20,11 @@ A proposed change that conflicts with an invariant requires an explicit owner de
 
 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.
+The normal handoff is: the repository owner publishes the reviewed npm version, then runs `npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest && machine-mcp`. The npm command updates the global CLI but cannot hot-reload an existing Node process. The subsequent normal foreground startup validates the Worker deployment hash, expected version, and health, requests shutdown of an active autostart daemon, waits a bounded interval for its lock, redeploys when necessary, and then takes over with the installed version. Live operations require explicit authorization even when they appear to be the obvious next release step.
+
+## Default instruction invariant
+
+A new installation must provide useful, conservative agent working agreements without requiring the user to create instruction files. The default context is generated in memory, is bounded and inspectable, writes no home/repository files, exposes no package-script bodies or source contents, and remains lower precedence than explicit user/repository guidance. Repository configuration cannot disable user-global baseline controls. Instructions remain behavioral guidance; hard restrictions belong to policy, permissions, approvals, hooks, or external isolation.
 
 ## Architectural boundaries
 

package/docs/LOGGING.md

@@ -80,7 +80,8 @@ The implementation omits:
 - connection passwords, daemon secrets, authorization codes, and access tokens;
 - registered resource values and source paths;
 - browser pairing tokens, page URLs/source, DOM metadata, form values, uploaded file bytes, and screenshots;
-- application names, Accessibility trees, selectors, and entered values.
+- application names, Accessibility trees, selectors, and entered values;
+- built-in instruction text, automatic project facts, package script names, and explicit instruction-file contents.
 
 Unexpected infrastructure failures are reduced to coarse error classes in normal logs. Client-facing tool errors may contain more detail according to the active path-display policy, but those details are not copied into operational logs.
 

package/docs/OPERATIONS.md

@@ -57,6 +57,29 @@ The machine-level broker permits multiple workspace daemons/stdio clients to sha
 
 Application UI inspection/actions require Accessibility permission for the Node/Machine Bridge process. Grant it in macOS Privacy & Security, then retry `inspect_local_application`. Opening applications does not require the same Accessibility authority. If an app changes UI hierarchy or localizes labels, inspect again and use role/identifier/index selectors instead of assuming a stale title.
 
+## Foreground startup, background service, and upgrades
+
+`machine-mcp` is a foreground command. It remains attached to the terminal, defaults to `info` logging, and stops on `Ctrl+C`. `machine-mcp service start` launches the installed platform service in the background and returns to the shell; that service uses `warn` logging.
+
+A global npm install changes the CLI files on disk but does not replace an already running Node process. On a normal foreground start, Machine Bridge unloads the platform service and then independently examines the workspace daemon lock. This second path handles a detached/orphan `--daemon-only` process that launchd/systemd/task scheduling no longer tracks, including legacy locks without mode/version metadata. Before sending `SIGTERM`, Machine Bridge verifies the live command line against the lock, entrypoint, canonical workspace, canonical state root, and daemon-only flag. It waits up to 15 seconds for both the PID and lock to disappear and never escalates to a forced kill. A foreground or unverifiable process is left untouched; stop a foreground instance with `Ctrl+C`.
+
+`machine-mcp service status [WORKSPACE]` reports two independent layers: the platform service (`active`) and `workspace_daemon`, plus `effective_active` and `orphaned_workspace_daemon` summary flags. On macOS it is possible for launchd to report inactive while a prior Node process remains alive with parent PID 1; that is an orphan-daemon condition, not proof that the daemon stopped. `service stop` now unloads the provider when present and then terminates only a verified service-style workspace daemon. If takeover reaches its deadline, run:
+
+```sh
+machine-mcp service stop
+machine-mcp service status
+machine-mcp --verbose
+```
+
+Recommended upgrade:
+
+```sh
+npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+machine-mcp --verbose
+```
+
+Keep `--omit=optional` in the install command. Without it npm may resolve optional `fsevents` and warn that its install script was not included in `allowScripts`; Machine Bridge does not require that development-time watcher at runtime.
+
 ## 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. 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.

package/docs/PRIVACY.md

@@ -27,6 +27,14 @@ Machine-specific operational notes may be kept under the ignored `.project-local
 
 Ignored does not mean safe for secrets: do not store passwords, tokens, private keys, authorization URLs, or copied secret-bearing logs there. `.privacy-denylist` remains the dedicated local vocabulary gate.
 
+## Runtime instruction context
+
+When automatic project context is enabled, Machine Bridge sends a small generated block through the same authorized MCP transport as other session instructions. It may contain the target path relative to the repository root, recognized project/build filenames, package-manager and lockfile names, package script names, runtime constraints, common documentation filenames, and CI workflow filenames.
+
+The generator does not include package script bodies, dependency names or versions, source/document contents, environment values, absolute home paths, or command output. It executes nothing and writes no repository or user files. File and script names can still reveal project structure, so users who do not want that metadata to traverse a remote Worker/host can set `"automatic_project_context": false` in `~/.config/machine-bridge-mcp/agent.json`. Built-in instructions can be disabled separately with `"builtin_instructions": false`.
+
+Neither generated nor explicit instruction content is written to ordinary operational logs.
+
 ## Review rules
 
 Before committing or publishing:

package/docs/TESTING.md

@@ -17,7 +17,8 @@ The suite includes:
 - 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;
-- global `model_instructions_file` injection in stdio/remote initialization, hierarchical agent-context precedence, live skill rescanning/fingerprints, automatic task ranking/loading, command override/removal, direct argv handling, timeout ceilings, and execution-profile denial;
+- default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, live project/skill rescanning and fingerprints, automatic task ranking/loading, command override/removal, direct argv handling, timeout ceilings, and execution-profile denial;
+- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, foreground-process protection, actual-PID exit waiting, non-forcing timeout guidance, daemon lock mode/version metadata, launchd service-target semantics, and silent idempotent duplicate service starts;
 - machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, and broker result redaction;
 - canonical path and symbolic-link escape tests;
 - relative-path privacy and error-path redaction tests;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -44,7 +44,7 @@
     "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/agent-context.mjs && node --check src/local/browser-bridge.mjs && node --check src/local/app-automation.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/browser-bridge-test.mjs && node --check tests/app-automation-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 && node --check browser-extension/service-worker.js && node --check browser-extension/pairing.js && node --check browser-extension/page-automation.js",
+    "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/default-instructions.mjs && node --check src/local/daemon-process.mjs && node --check src/local/browser-bridge.mjs && node --check src/local/app-automation.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/browser-bridge-test.mjs && node --check tests/app-automation-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 && node --check browser-extension/service-worker.js && node --check browser-extension/pairing.js && node --check browser-extension/page-automation.js",
     "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 browser-bridge:test && npm run app-automation: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",