@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/worktree-core.js

@@ -186,9 +186,15 @@ const CLEANUP_FAILURE_DIAGNOSTIC = "untracked-file cleanup did not complete; con
  * settings, MCP registrations/trust, and worker logging are provisioned again — so
  * anything cleanup removes is re-created by the provisioning that follows it.
  *
- * Stale, non-ignored `.conductor/result.json` and `.conductor/critique.md` from a
- * prior attempt are removed intentionally: a leftover verdict artifact read by a
- * later attempt would be a prior run's answer presented as this one's.
+ * `.conductor/` content is NOT removed here, and must not be assumed to be
+ * (BAPI-814/D1). `.conductor/` is an ignored path in this repository, and `-fd`
+ * without `-x` leaves ignored paths alone — so a prior attempt's
+ * `.conductor/result.json` and `.conductor/critique.md` survive this cleanup
+ * entirely. Removing them is the ATTEMPT OWNER's job, performed explicitly in
+ * `executor/job-runner.ts` after the worktree lock is acquired and before the
+ * worker spawns (`removeStaleVerdictArtifacts`). That placement is deliberate:
+ * cleanup must be serialized against the lock, whereas this function runs during
+ * unlocked worktree preparation.
  *
  * FAIL-OPEN. Pre-change behavior performed no cleanup at all, so being unable to
  * clean must never change the worktree row or the job outcome. Every failure path —

package/docs/install/mcp-tool-integrations.md

@@ -58,7 +58,8 @@ activated. `core` is always implicitly included.
 | `core` | always |
 | `pipeline-authoring` | `BRIDGE_MCP_PROFILE` includes `pipeline-authoring` or `full` |
 | `conductor` | includes `conductor` or `full` |
-| `sfcc` | includes `sfcc` or `full` (2 diagnostics ship in `core`; the rest are gated) |
+| `sfcc` | includes `sfcc` or `full` — the OCAPI **read** tools and `sfcc_log_query` (2 diagnostics ship in `core`) |
+| `sfcc-write` | includes `sfcc-write` or `full` — the destructive SFCC **write** tools. Independent of `sfcc`: neither group implies the other (BAPI-817) |
 
 The `pipeline-authoring` tools live in `index.ts` alongside core, gated by
 `ACTIVE_GROUPS.has("pipeline-authoring")`.
@@ -178,10 +179,43 @@ by tier.
 | Tool | Dependencies (class) |
 |---|---|
 | `create_pull_request` | VCS **[BLOCK]** (Tier-1) |
+| `merge_pull_request` | VCS **[BLOCK]** (Tier-1; protected server-decided merge — see below) |
 | `resolve_ci_checks` | VCS **[BLOCK]** (Tier-1) |
 | `poll_ci_checks` | VCS **[BLOCK]** (Tier-1); also **hidden until `ci_check_config` is resolved** (needs a prior `resolve_ci_checks`) |
 | `materialize_fresh_base` | VCS / git base ref **[BLOCK]** (Tier-1; materializes a pinned base tree) |
 
+#### `merge_pull_request` — what the caller can observe
+
+The tool holds no VCS credential and performs no merge of its own; it asks the
+server and reports the answer. Four constraints are worth knowing before calling it:
+
+- **Only `merged: true` is success.** `dry_run`, `pending_approval`, and
+  `lease_held` are non-progress outcomes — nothing was merged, and repeating the
+  call unchanged will produce the same answer until the named condition moves.
+- **Workflow files are refused.** The server reads the pull request's complete
+  changed-file list and declines any PR touching `.github/workflows/`, including a
+  file *renamed out of* that directory. A file list it cannot prove complete is
+  refused the same way, as `workflow_files_unreadable` — an unreadable diff is not
+  a clean one.
+- **`auto_merge_enabled` must be on.** Merge configuration that is missing,
+  disabled, or malformed produces `dry_run` rather than a merge. Enable it on the
+  project default via `PUT /jira/epic-runs/supervisor-config/defaults/`; the
+  `dry_run` envelope carries that exact remediation in its `hint`.
+- **No required checks, no merge.** When no authoritative required-check set can be
+  resolved, the tool returns `gate_unresolved` and never sends the merge request —
+  "zero required checks are all green" is not a CI pass.
+- **Review is refused too, when the repository opts in.** If the done gate carries a
+  `review_state` condition, the tool also refuses when the verdict is not approving
+  for the exact `expected_head_sha`. `review_not_approved` is a wait — a verdict for
+  this head may still be posted, so it carries `retry_hint: "retry_later"`. The other
+  four need intervention (`needs_human`): `review_unavailable` (review state could not
+  be read), `review_source_unsupported` (`min_approvals` / `combination`, refused
+  rather than downgraded), `review_config_invalid` (review configuration exists but is
+  malformed), and `head_sha_drift` (the verdict belongs to a different commit). The
+  tool's own check is advisory; the server's head-bound review observation is
+  authoritative, so a tool-side pass followed by a server refusal is expected for a
+  legacy approved comment that carries no head proof.
+
 ### Full-automation (composite)
 
 These orchestrate an idea → ticket → review → start chain, so they inherit the
@@ -239,11 +273,16 @@ integration dependency.
 | `sfcc_setup_status` | — none (its purpose is to report which SFCC prerequisites are missing) |
 | `check_permissions` | SFCC OCAPI **[BLOCK]** (probes OCAPI; reports not-OK without access / version config) |
 
-### Gated behind the `sfcc` group
+### Gated behind the `sfcc` group (reads + logs)
 
 All are profile-gated **[BLOCK]** to register, and all require SFCC OCAPI creds +
-`version` config + a reachable sandbox → SFCC OCAPI **[BLOCK]**. Writes are
-sandbox-only and destructive.
+`version` config + a reachable sandbox → SFCC OCAPI **[BLOCK]**.
+
+Every SFCC tool — including the two always-on diagnostics above — additionally
+crosses the resolved-hostname sandbox boundary at invocation time: if the host
+the credentials resolve to is not a recognized developer sandbox, the call is
+refused with `403 TARGET_NOT_SANDBOX` before any request leaves the machine
+(BAPI-817).
 
 **Reads:**
 
@@ -258,7 +297,13 @@ sandbox-only and destructive.
 | `site_preference_get` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
 | `site_preference_search` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
 
-**Writes (9, sandbox-only):**
+### Gated behind the `sfcc-write` group
+
+Writes are destructive and sandbox-only. They are **not** registered by the
+`sfcc` group — enabling introspection must never enable mutation — so a session
+wanting both selects `sfcc,sfcc-write` (or `full`).
+
+**Writes (sandbox-only):**
 
 | Tool | Dependencies (class) |
 |---|---|
@@ -272,7 +317,7 @@ sandbox-only and destructive.
 | `custom_object_definition_attribute_update` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
 | `site_preference_values_set` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
 
-**Logs:**
+**Logs** (gated by `sfcc`, not `sfcc-write`)**:**
 
 | Tool | Dependencies (class) |
 |---|---|
@@ -286,12 +331,12 @@ sandbox-only and destructive.
 |---|---|---|
 | **Ticket backend** (jira mode) | `create_ticket`, `get_ticket(s)`, `update_ticket_description`, `update_jira_status`, `get_jira_transitions`, and every AI generator (they read the ticket) | — |
 | **Jira (only)** | `get_comments`, `add_comment`, `attachment`, `estimate_epic` | — |
-| **Version control (VCS)** | `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `materialize_fresh_base`, `parse_repository`, `regenerate_directory_map`, `wait_for_done_gate`; **Tier-3** `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `request_reimplement_context`/`get_reimplement_context`, `create_doc`(tdd/architecture) | **Tier-4** `request_clarifying_questions`, `request_ticket_critique`, `request_ticket_review`, `request_prd`, `create_doc`(prd/fsd) |
+| **Version control (VCS)** | `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `materialize_fresh_base`, `parse_repository`, `regenerate_directory_map`, `wait_for_done_gate`; **Tier-3** `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `request_reimplement_context`/`get_reimplement_context`, `create_doc`(tdd/architecture) | **Tier-4** `request_clarifying_questions`, `request_ticket_critique`, `request_ticket_review`, `request_prd`, `create_doc`(prd/fsd) |
 | **Code index** (succeeded parse) | Tier-3 plan/architecture/reimplement/`create_doc`(tdd/architecture); `request_council` in `technical`/`discovery` modes | Tier-4 clarifying-questions/critique/review/prd/fsd |
-| **SFCC OCAPI** | `check_permissions` + all 16 SFCC read/write tools | — |
+| **SFCC OCAPI** | `check_permissions` + every gated SFCC read and write tool | — |
 | **SFCC WebDAV logs** | `sfcc_log_query` | — |
 | **Deep-research flag** | `request_deep_research`, `get_deep_research` | — |
-| **Profile gating** | all `pipeline-authoring`, `conductor`, and gated `sfcc` tools | — |
+| **Profile gating** | all `pipeline-authoring`, `conductor`, `sfcc`, and `sfcc-write` tools | — |
 
 ## Notes & caveats
 

package/docs/install/sfcc-integration.md

@@ -6,11 +6,25 @@ small set of sandbox-only writes — through the **OCAPI Data API**. This guide
 setting up the OCAPI client that those tools authenticate against.
 
 > **Sandbox / local development only.** This integration is intended for a **developer
-> sandbox**. The tools reject non-sandbox instances, and the permissions grant below is
-> deliberately broad (all methods, all resources) — appropriate for a throwaway dev
-> sandbox, **never** for staging or production. Do not configure this grant on any
-> instance that holds real data. Credentials stay local (in `dw.json` or `SFCC_*` env
-> vars) and are never sent to Bridge.
+> sandbox**, and that restriction is **enforced in code**: before any SFCC tool runs,
+> Bridge validates the hostname your credentials actually resolve to — from `dw.json`
+> or `SFCC_*` — against the sandbox forms listed below. An unrecognized host is refused
+> with a `403` (`error.code: "TARGET_NOT_SANDBOX"`) before any request leaves your
+> machine. The check reads the resolved hostname, never the `instance` tool argument,
+> so omitting `instance` or passing `"sandbox"` cannot bypass it.
+>
+> Accepted sandbox hostname forms:
+>
+> - `<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com`
+> - `<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com`
+> - `<realm>-<nnn>.dx.commercecloud.salesforce.com`
+>
+> Anything else — a `production-`/`staging-`/`development-` prefixed host, or any
+> `*.demandware.net` host — is rejected.
+>
+> Still do not configure the grants below on an instance that holds real data.
+> Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to
+> Bridge.
 
 For the full per-tool list and what each SFCC tool depends on, see
 [MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference
@@ -34,20 +48,39 @@ In Business Manager for the sandbox:
 
 **Administration → Site Development → Open Commerce API Settings → Data API** tab.
 
-Add the following client entry to the `clients` array of the Data API settings, then
-**Save**. This grants the client full read/write access to every Data API resource —
-acceptable only on a developer sandbox:
+Add the client entry below to the `clients` array of the Data API settings, then
+**Save**. It grants only the resource families and HTTP methods Bridge's SFCC tools
+actually call — not a global `/**` grant. `check_permissions` prints the same JSON on
+a 401/403, split into the two blocks.
+
+**READ/SEARCH TOOL GRANTS** — required by the `sfcc` read tools. (`post` is OCAPI's
+convention for its `*_search` endpoints, not a mutation.)
+
+```json
+{
+  "client_id": "<your-client-id-here>",
+  "resources": [
+    { "resource_id": "/system_object_definitions",    "methods": ["get"],         "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/system_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/site_preferences/**",          "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/custom_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" }
+  ]
+}
+```
+
+**MUTATION GRANTS** — required **only if you enable `BRIDGE_MCP_PROFILE=sfcc-write`**,
+which registers the nine destructive write tools. These are shipped capabilities, not
+future work. No `delete` is granted, because no shipped write tool performs one; the
+`get` entries are needed for the If-Match ETag round trip that precedes each `PATCH`.
 
 ```json
 {
   "client_id": "<your-client-id-here>",
   "resources": [
-    {
-      "methods": ["get", "post", "put", "patch", "delete"],
-      "read_attributes": "(**)",
-      "write_attributes": "(**)",
-      "resource_id": "/**"
-    }
+    { "resource_id": "/system_object_definitions",    "methods": ["get"],                  "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/system_object_definitions/**", "methods": ["get", "put", "patch"],  "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/custom_object_definitions/**", "methods": ["get", "put", "patch"],  "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/site_preferences/**",          "methods": ["get", "patch"],         "read_attributes": "(**)", "write_attributes": "(**)" }
   ]
 }
 ```
@@ -57,7 +90,9 @@ Notes:
 - The `client_id` **must match** the Account Manager API client whose credentials you
   put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if
   it differs.
-- If the Data API settings are empty, wrap the entry in the standard settings envelope:
+- If the Data API settings are empty, wrap the entries in the standard settings
+  envelope. Merge the resource lists from the block(s) above into one `resources`
+  array — do not substitute a global `"resource_id": "/**"` grant:
 
   ```json
   {
@@ -66,12 +101,10 @@ Notes:
       {
         "client_id": "<your-client-id-here>",
         "resources": [
-          {
-            "methods": ["get", "post", "put", "patch", "delete"],
-            "read_attributes": "(**)",
-            "write_attributes": "(**)",
-            "resource_id": "/**"
-          }
+          { "resource_id": "/system_object_definitions",    "methods": ["get"],         "read_attributes": "(**)", "write_attributes": "(**)" },
+          { "resource_id": "/system_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+          { "resource_id": "/site_preferences/**",          "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+          { "resource_id": "/custom_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" }
         ]
       }
     ]
@@ -109,14 +142,28 @@ or the `/teach-bridge` skill.
 ## 4. Enable the SFCC tools
 
 The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always
-registered. The read tools, write tools, and `sfcc_log_query` are gated behind the
-`sfcc` profile. Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is
-comma-separated; `full` also works), then **restart the MCP client**:
+registered. Everything else is gated, behind **two independent profile groups**:
+
+| Group | Registers |
+|---|---|
+| `sfcc` | the 8 OCAPI read tools + `sfcc_log_query` — read-only |
+| `sfcc-write` | the 9 destructive write tools |
+
+Neither implies the other. Add what you need to `BRIDGE_MCP_PROFILE` in the MCP server
+`env` block (it is comma-separated), then **restart the MCP client**:
 
 ```json
 "env": { "BRIDGE_MCP_PROFILE": "sfcc" }
 ```
 
+For reads plus writes, use `"sfcc,sfcc-write"`. `full` expands to every group and is
+therefore write-capable.
+
+> **Migration.** `sfcc` used to register the nine write tools too. It no longer does.
+> If you were relying on SFCC writes through `BRIDGE_MCP_PROFILE=sfcc`, change it to
+> `BRIDGE_MCP_PROFILE=sfcc,sfcc-write`. `full` users keep write access and need no
+> change.
+
 ## 5. Verify
 
 Ask your agent to run:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "test": "npm run test:normal && npm run test:module-mocks",
     "test:normal": "node scripts/run-unit-tests.js normal",
     "test:module-mocks": "node scripts/run-unit-tests.js module-mocks",
-    "test:integration": "node --test build/integration/refresh-main.integration.test.js build/integration/command-provisioning.integration.test.js build/integration/start-tickets.integration.test.js build/integration/start-tickets-tier-handoff.integration.test.js build/integration/doctor.integration.test.js build/integration/agent-capabilities.integration.test.js build/integration/conductor-producer.integration.test.js build/integration/conductor-message-relay.integration.test.js build/integration/executor-http-runner.integration.test.js build/integration/executor-job-behaviors.integration.test.js build/integration/executor-recovery-jobs.integration.test.js build/integration/executor-spec-review-prompt.integration.test.js build/integration/resume-pre-spawn.git.integration.test.js build/integration/worker-finalization-origin.integration.test.js build/integration/post-remediation-merge-ci-wait.integration.test.js build/integration/executor-merge-supervision.integration.test.js build/integration/attachment-binary-roundtrip.integration.test.js build/integration/dependent-ticket-fresh-base.integration.test.js build/integration/execute-plan-instructions.integration.test.js build/integration/implement-ticket-finalization-order.integration.test.js build/integration/conductor-bundle-artifacts.integration.test.js build/integration/install-bridge-repo-resolution.integration.test.js build/integration/capability-report-contract.integration.test.js build/integration/request-brainstorm-general.integration.test.js build/integration/request-council-trigger-drop.integration.test.js build/integration/install-bridge-onboarding-launch.integration.test.js build/integration/install-bridge-conductor.integration.test.js build/integration/install-bridge-failure-guards.integration.test.js build/integration/learn-repository-pipeline.integration.test.js build/integration/visual-diff-mcp.integration.test.js build/integration/executor-mcp-provisioning.integration.test.js build/integration/executor-worktree-reentry.integration.test.js build/integration/sfcc-read-error-contract.integration.test.js build/integration/sfcc-response-envelope.integration.test.js build/integration/sfcc-total-error-contract.integration.test.js build/integration/serve-stdio.integration.test.js build/integration/install-alias.integration.test.js build/integration/setup-epic-validation.integration.test.js build/integration/plane-cli.integration.test.js",
+    "test:integration": "node --test build/conductor/conductor-runtime.integration.test.js build/integration/refresh-main.integration.test.js build/integration/command-provisioning.integration.test.js build/integration/start-tickets.integration.test.js build/integration/start-tickets-tier-handoff.integration.test.js build/integration/doctor.integration.test.js build/integration/agent-capabilities.integration.test.js build/integration/conductor-producer.integration.test.js build/integration/conductor-message-relay.integration.test.js build/integration/executor-http-runner.integration.test.js build/integration/executor-job-behaviors.integration.test.js build/integration/executor-recovery-jobs.integration.test.js build/integration/executor-spec-review-prompt.integration.test.js build/integration/resume-pre-spawn.git.integration.test.js build/integration/executor-containment.git.integration.test.js build/integration/conduct-epic-cli.integration.test.js build/integration/conduct-epic-corrections.integration.test.js build/integration/worker-finalization-origin.integration.test.js build/integration/post-remediation-merge-ci-wait.integration.test.js build/integration/executor-merge-supervision.integration.test.js build/integration/attachment-binary-roundtrip.integration.test.js build/integration/dependent-ticket-fresh-base.integration.test.js build/integration/execute-plan-instructions.integration.test.js build/integration/implement-ticket-finalization-order.integration.test.js build/integration/conductor-bundle-artifacts.integration.test.js build/integration/install-bridge-repo-resolution.integration.test.js build/integration/capability-report-contract.integration.test.js build/integration/request-brainstorm-general.integration.test.js build/integration/request-council-trigger-drop.integration.test.js build/integration/install-bridge-onboarding-launch.integration.test.js build/integration/install-bridge-conductor.integration.test.js build/integration/install-bridge-conductor-executor.integration.test.js build/integration/install-bridge-failure-guards.integration.test.js build/integration/learn-repository-pipeline.integration.test.js build/integration/visual-diff-mcp.integration.test.js build/integration/executor-mcp-provisioning.integration.test.js build/integration/executor-worktree-reentry.integration.test.js build/integration/sfcc-read-error-contract.integration.test.js build/integration/sfcc-read-surface.integration.test.js build/integration/sfcc-response-envelope.integration.test.js build/integration/sfcc-total-error-contract.integration.test.js build/integration/sfcc-target-boundary.integration.test.js build/integration/serve-stdio.integration.test.js build/integration/install-alias.integration.test.js build/integration/setup-epic-validation.integration.test.js build/integration/plane-cli.integration.test.js build/integration/executor-auth-retirement.integration.test.js build/integration/decision-implications-command-scaffold.test.js build/integration/strict-mcp-worker-contract.test.js build/integration/executor-adapter-flow.test.js build/integration/install-cli-contract.integration.test.js build/integration/inline-phase-state-tools.test.js",
     "test:smoke": "node --test build/integration/packaged-cli-smoke.test.js",
     "canary:agent-capabilities": "npm run build && node scripts/agent-capabilities-canary.mjs",
     "prepublishOnly": "node scripts/bundle-assets.js && npm run build && node scripts/verify-shebang.cjs"
@@ -55,7 +55,7 @@
     "node": ">=18.0.0"
   },
   "overrides": {
-    "fast-uri": ">=4.1.1",
+    "fast-uri": ">=4.1.2",
     "hono": ">=4.13.1",
     "@hono/node-server": "^1.19.13",
     "ip-address": ">=10.1.1"

package/build/executor/worker-config-isolation.js

@@ -1,287 +0,0 @@
-/** Restrictive mode for the isolation directory itself (owner-only). */
-export const ISOLATION_DIR_MODE = 0o700;
-/** Owner-only mode for the seeded Bridge credential file. */
-export const ISOLATION_FILE_MODE = 0o600;
-/**
- * Fixed name prefix for every directory this module creates. The startup sweep
- * recognizes ONLY this prefix, which is what keeps it from deleting unrelated
- * temporary directories that happen to share the parent.
- */
-export const ISOLATION_DIR_PREFIX = "bapi-conductor-claude-cfg-";
-/**
- * Age past which the startup sweep may remove an orphan, deliberately far above
- * any supported worker lifetime (the longest executor job timeout is measured in
- * hours, not days). A directory younger than this may still belong to a LIVE
- * worker owned by a concurrent executor process, so the threshold is the only
- * thing preventing the sweep from deleting an in-use configuration.
- */
-export const ISOLATION_ORPHAN_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-/** Platforms whose POSIX mode model supports the `0700` containment above. */
-const SUPPORTED_PLATFORMS = ["darwin", "linux"];
-/** Fixed remediation text per reason. Never includes a path or a value. */
-const REASON_MESSAGES = {
-    "unsupported-platform": "worker config isolation is not supported on this platform (POSIX 0700/0600 containment is required)",
-    "unsupported-auth-layout": "no ANTHROPIC_API_KEY is available to the executor; an OAuth/subscription-only login does not " +
-        "follow an isolated CLAUDE_CONFIG_DIR, and copying operator credentials is not permitted",
-    "missing-filesystem-dependency": "the executor was constructed without the filesystem boundaries worker config isolation requires",
-    "unsafe-isolation-parent": "the isolation parent directory is a symbolic link or not a directory; refusing to create an " +
-        "isolated config directory beneath it",
-    "directory-creation-failed": "the isolated config directory could not be created or permissioned",
-};
-/**
- * Render a capability failure as a bounded, secret-free sentence naming only the
- * platform and the fixed reason — the exact text posted as an `error_message`.
- */
-export function formatWorkerConfigIsolationReason(platform, reason) {
-    return `worker config isolation unavailable on ${platform}: ${REASON_MESSAGES[reason]}`;
-}
-/**
- * Decide whether isolation CAN be established here, without creating anything.
- *
- * Read-only by construction — this is what lets `doctor` reuse it (BAPI-731
- * requirement 4) while keeping doctor's no-writes contract. It never reads the
- * operator's `.claude.json`, never touches the credential store, and never
- * returns a credential value: the auth check is presence-only.
- */
-export function evaluateWorkerConfigIsolationCapability(deps) {
-    const platform = String(deps.platform);
-    if (!SUPPORTED_PLATFORMS.includes(deps.platform)) {
-        return { supported: false, platform, reason: "unsupported-platform" };
-    }
-    // Presence-only. The VALUE is never read into any result, log, or diagnostic.
-    const apiKey = deps.env?.ANTHROPIC_API_KEY;
-    if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
-        return { supported: false, platform, reason: "unsupported-auth-layout" };
-    }
-    return { supported: true, platform, strategy: "api-key-env" };
-}
-function failure(platform, reason) {
-    return {
-        ok: false,
-        platform,
-        reason,
-        message: formatWorkerConfigIsolationReason(platform, reason),
-    };
-}
-/**
- * Create a private, owner-only configuration directory for ONE job attempt.
- *
- * The directory lives under the executor's temporary root — never inside the
- * worktree, which would put executor-owned state into the diff the worker is
- * about to commit and would be destroyed by the worktree's own reset/clean paths.
- *
- * Seeds NOTHING of the operator's Claude configuration. Inventory finding 3
- * established that no trust entry is needed to keep a headless worker from
- * prompting, and finding 4 established that the ANTHROPIC credential travels in
- * the environment. No projected fragment of the operator's configuration is
- * written, so none can get stale or over-grant.
- *
- * The single exception is {@link SeededBridgeCredential} — see that type for why
- * an empty directory is NOT sufficient for the Bridge credential specifically:
- * finding 4 does not extend to `BAPI_API_KEY`, which is denied from the worker
- * environment on purpose, leaving the redirected store as its only route in.
- */
-export async function establishWorkerConfigIsolation(deps, options = {}) {
-    const capability = evaluateWorkerConfigIsolationCapability(deps);
-    if (!capability.supported) {
-        return failure(capability.platform, capability.reason);
-    }
-    const platform = capability.platform;
-    let parent;
-    try {
-        parent = deps.tmpdir();
-    }
-    catch {
-        return failure(platform, "unsafe-isolation-parent");
-    }
-    if (typeof parent !== "string" || parent.length === 0) {
-        return failure(platform, "unsafe-isolation-parent");
-    }
-    // Reject a symlinked or non-directory parent BEFORE creating anything beneath
-    // it: `mkdtemp` under a symlink would silently place a credential-adjacent
-    // directory wherever the link points.
-    try {
-        const parentMeta = await deps.lstatPath(parent);
-        if (!parentMeta || parentMeta.isSymbolicLink || !parentMeta.isDirectory) {
-            return failure(platform, "unsafe-isolation-parent");
-        }
-    }
-    catch {
-        return failure(platform, "unsafe-isolation-parent");
-    }
-    // `mkdtemp` is atomic and collision-free, so two concurrent jobs on the same
-    // executor can never be handed the same directory.
-    let created;
-    try {
-        created = await deps.mkdtemp(deps.join(parent, ISOLATION_DIR_PREFIX));
-        if (typeof created !== "string" || created.length === 0) {
-            return failure(platform, "directory-creation-failed");
-        }
-    }
-    catch {
-        // The raw error may carry a host path; only the fixed reason escapes.
-        return failure(platform, "directory-creation-failed");
-    }
-    // Verify what we actually got is a real directory and not a link, then narrow
-    // it to owner-only. `mkdtemp` already creates at 0700 on POSIX; the explicit
-    // chmod makes the guarantee independent of the platform's umask behavior.
-    try {
-        const meta = await deps.lstatPath(created);
-        if (!meta || meta.isSymbolicLink || !meta.isDirectory) {
-            await safeDispose(deps, created);
-            return failure(platform, "unsafe-isolation-parent");
-        }
-        await deps.chmod(created, ISOLATION_DIR_MODE);
-    }
-    catch {
-        await safeDispose(deps, created);
-        return failure(platform, "directory-creation-failed");
-    }
-    // The isolated XDG root lives INSIDE the disposable directory, so a single
-    // recursive removal reclaims both and no second lifetime needs tracking.
-    const xdgConfigHome = deps.join(created, "xdg");
-    try {
-        await deps.mkdir(xdgConfigHome, { recursive: true });
-        await deps.chmod(xdgConfigHome, ISOLATION_DIR_MODE);
-    }
-    catch {
-        await safeDispose(deps, created);
-        return failure(platform, "directory-creation-failed");
-    }
-    // Seed the one credential the redirect would otherwise strip. Fail-CLOSED,
-    // matching this module's posture: a worker that cannot reach its Bridge MCP
-    // tools cannot do the job it was dispatched for, and the failure mode is a
-    // clean exit that looks like success. Refusing to spawn is strictly better
-    // than spawning a worker guaranteed to accomplish nothing.
-    const credential = options.bridgeCredential;
-    if (credential) {
-        if (!deps.writeFile) {
-            await safeDispose(deps, created);
-            return failure(platform, "missing-filesystem-dependency");
-        }
-        try {
-            const bridgeDir = deps.join(xdgConfigHome, "bridge");
-            await deps.mkdir(bridgeDir, { recursive: true });
-            await deps.chmod(bridgeDir, ISOLATION_DIR_MODE);
-            const storePath = deps.join(bridgeDir, "credentials.json");
-            await deps.writeFile(storePath, 
-            // Exactly the shape resolveCredentialBundle reads: a logical target
-            // mapping to its named secret values.
-            `${JSON.stringify({ [`bapi:${credential.repoName}`]: { BAPI_API_KEY: credential.apiKey } }, null, 2)}\n`);
-            // Narrow AFTER writing: the content is secret, and a permissive window
-            // between create and chmod is the whole risk being closed here.
-            await deps.chmod(storePath, ISOLATION_FILE_MODE);
-        }
-        catch {
-            // The raw error may carry a host path or the secret; only the fixed
-            // reason escapes.
-            await safeDispose(deps, created);
-            return failure(platform, "directory-creation-failed");
-        }
-    }
-    let disposed = false;
-    return {
-        ok: true,
-        isolation: {
-            claudeConfigDir: created,
-            xdgConfigHome,
-            async dispose() {
-                if (disposed)
-                    return null;
-                disposed = true;
-                try {
-                    await deps.rmRecursive(created);
-                    return null;
-                }
-                catch {
-                    // Best-effort by contract: cleanup failure must never replace an
-                    // already-determined job outcome, and the raw error never escapes.
-                    return "worker config isolation directory could not be removed";
-                }
-            },
-        },
-    };
-}
-/** Remove a partially-created directory, swallowing every failure. */
-async function safeDispose(deps, path) {
-    try {
-        await deps.rmRecursive(path);
-    }
-    catch {
-        /* best-effort */
-    }
-}
-/**
- * Remove stale isolation directories left behind by an ungraceful executor exit
- * (SIGKILL, OOM, host reboot) where per-job disposal never ran.
- *
- * Deliberately conservative, because this function deletes directories: it looks
- * only inside the executor's own temporary root, recognizes only entries
- * carrying {@link ISOLATION_DIR_PREFIX}, requires NON-following metadata to say
- * the entry is a real directory (so a symlink is skipped rather than followed),
- * and requires an age beyond {@link ISOLATION_ORPHAN_MAX_AGE_MS} so a live
- * concurrent executor's active job directory is never removed.
- *
- * Never throws: startup must proceed even if the sweep cannot run at all.
- */
-export async function sweepOrphanedWorkerConfigDirectories(deps) {
-    const result = { removed: 0, skipped: 0, diagnostics: [] };
-    const maxAgeMs = typeof deps.maxAgeMs === "number" ? deps.maxAgeMs : ISOLATION_ORPHAN_MAX_AGE_MS;
-    let parent;
-    try {
-        parent = deps.tmpdir();
-        if (typeof parent !== "string" || parent.length === 0) {
-            result.diagnostics.push("worker config isolation sweep skipped: no temporary root");
-            return result;
-        }
-    }
-    catch {
-        result.diagnostics.push("worker config isolation sweep skipped: no temporary root");
-        return result;
-    }
-    let entries;
-    try {
-        entries = await deps.readdir(parent);
-    }
-    catch {
-        result.diagnostics.push("worker config isolation sweep skipped: temporary root unreadable");
-        return result;
-    }
-    const cutoff = deps.now() - maxAgeMs;
-    for (const entry of entries) {
-        // Prefix match FIRST: anything the module did not create is not ours to
-        // delete, whatever its age.
-        if (typeof entry !== "string" || !entry.startsWith(ISOLATION_DIR_PREFIX)) {
-            result.skipped += 1;
-            continue;
-        }
-        const candidate = deps.join(parent, entry);
-        let meta;
-        try {
-            meta = await deps.lstatPath(candidate);
-        }
-        catch {
-            result.skipped += 1;
-            continue;
-        }
-        // A symlink is skipped, never followed — removing it recursively could
-        // delete whatever it points at.
-        if (!meta || meta.isSymbolicLink || !meta.isDirectory) {
-            result.skipped += 1;
-            continue;
-        }
-        if (!(meta.mtimeMs < cutoff)) {
-            result.skipped += 1;
-            continue;
-        }
-        try {
-            await deps.rmRecursive(candidate);
-            result.removed += 1;
-        }
-        catch {
-            result.skipped += 1;
-            result.diagnostics.push("worker config isolation sweep could not remove a stale directory");
-        }
-    }
-    return result;
-}