@twinsearth/w2m-dsh-plugin 1.3.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "exports": {
@@ -64,14 +64,14 @@
     "pack": "node scripts/pack.mjs",
     "reachability": "node scripts/reachability-check.mjs",
     "reachability:classify": "node scripts/reachability-classify.mjs",
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs",
     "test:acceptance-doc": "node --test --test-force-exit test/acceptance-doc.test.mjs",
     "test:account-identity": "node --test --test-force-exit test/account-identity.test.mjs",
     "test:account-join": "node --test --test-force-exit test/account-join.test.mjs",
     "test:admission": "node --test --test-force-exit test/admission.test.mjs",
     "test:admission-routes": "node --test --test-force-exit test/admission-routes.test.mjs",
     "test:agent": "node --test --test-force-exit test/agent.test.mjs test/memory.test.mjs",
-    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs",
+    "test:all": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/e2e.test.mjs test/crossnetwork.test.mjs test/signing-e2e.test.mjs test/outbound-only.test.mjs test/recovery.test.mjs test/pipeline-e2e.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-agent.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/p2p-crypto.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs",
     "test:approval-gate": "node --test --test-force-exit test/approval-gate.test.mjs",
     "test:approval-index": "node --test --test-force-exit test/approval-index.test.mjs",
     "test:authority": "node --test --test-force-exit test/authority.test.mjs",
@@ -141,7 +141,27 @@
     "test:chat-crypto": "node --test --test-force-exit test/chat-crypto.test.mjs",
     "test:reduce-suggestion": "node --test --test-force-exit test/reduce-suggestion.test.mjs",
     "test:merge-hint": "node --test --test-force-exit test/merge-hint.test.mjs",
-    "test:fleet-chat-route": "node --test --test-force-exit test/fleet-chat-route.test.mjs"
+    "test:fleet-chat-route": "node --test --test-force-exit test/fleet-chat-route.test.mjs",
+    "test:maintenance": "node --test --test-force-exit test/maintenance.test.mjs",
+    "test:maintenance-ferry": "node --test --test-force-exit test/maintenance-ferry.test.mjs",
+    "test:grant": "node --test --test-force-exit test/grant.test.mjs",
+    "test:grant-gate": "node --test --test-force-exit test/grant-gate.test.mjs",
+    "test:worktree": "node --test --test-force-exit test/worktree.test.mjs",
+    "test:patch-artifact": "node --test --test-force-exit test/patch-artifact.test.mjs",
+    "test:merge-queue": "node --test --test-force-exit test/merge-queue.test.mjs",
+    "test:m3-workflow": "node --test --test-force-exit test/m3-workflow.test.mjs",
+    "test:project-room": "node --test --test-force-exit test/project-room.test.mjs",
+    "test:project-attribution": "node --test --test-force-exit test/project-attribution.test.mjs",
+    "test:project-locks": "node --test --test-force-exit test/project-locks.test.mjs",
+    "test:project-reviews": "node --test --test-force-exit test/project-reviews.test.mjs",
+    "test:project-notifications": "node --test --test-force-exit test/project-notifications.test.mjs",
+    "test:blob-sessions": "node --test --test-force-exit test/blob-sessions.test.mjs",
+    "test:outbox": "node --test --test-force-exit test/outbox.test.mjs",
+    "test:metrics": "node --test --test-force-exit test/metrics.test.mjs",
+    "test:reliability-metrics": "node --test --test-force-exit test/metrics.test.mjs",
+    "test:evidence": "node --test --test-force-exit test/evidence.test.mjs",
+    "test:grant-issue": "node --test --test-force-exit test/grant-issue.test.mjs",
+    "test:project-refs": "node --test --test-force-exit test/project-refs.test.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -178,7 +198,8 @@
     "w2m-localside": "bin/w2m-localside.mjs",
     "w2m-mcp": "bin/w2m-mcp.mjs",
     "w2m-rabbit": "bin/w2m-rabbit.mjs",
-    "w2m-stun": "bin/w2m-stun.mjs"
+    "w2m-stun": "bin/w2m-stun.mjs",
+    "w2m-grant": "./bin/w2m-grant.mjs"
   },
   "disclosure": {
     "cloud": true,

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/acceptance/evidence.mjs

@@ -0,0 +1,79 @@
+/**
+ * Acceptance evidence validation (M7, v1.3.10-beta.24 slice).
+ *
+ * M7 says a capability is accepted only when its evidence is reproducible: a real task id, a real machine, an asserted result,
+ * a timestamp and an executor, stored in docs/acceptance/<version>/. This module is the schema those files must satisfy and the
+ * summary the release notes read. It validates the document; it cannot validate that the run happened, which is exactly why the
+ * remaining fields (task_id, machines, executed_at) are required rather than optional.
+ */
+export const EVIDENCE_KINDS = Object.freeze(['positive', 'negative', 'chaos']);
+export const EVIDENCE_EXECUTORS = Object.freeze(['lead', 'human', 'agent']);
+
+const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+const isArtifactSha = (value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+const isIsoTimestamp = (value) => typeof value === "string" && !Number.isNaN(Date.parse(value)) && /^\d{4}-\d{2}-\d{2}T/.test(value);
+
+/**
+ * Validate one evidence record. Returns every problem, not just the first: a release check should list what to fix.
+ */
+export function validateEvidence(record) {
+  const errors = [];
+  const fail = (code, field, message) => errors.push({ code, field, message });
+  if (record === null || typeof record !== "object" || Array.isArray(record)) {
+    return { ok: false, errors: [{ code: "EVIDENCE_NOT_OBJECT", field: null, message: "evidence must be a JSON object" }] };
+  }
+  if (!isNonEmptyString(record.version)) fail("VERSION_MISSING", "version", "version is required");
+  if (!isNonEmptyString(record.case) || !/^[A-Z0-9][A-Z0-9-]{0,79}$/.test(record.case)) fail("CASE_INVALID", "case", "case must be an uppercase id such as M1-LIVE-DIAG");
+  if (!EVIDENCE_KINDS.includes(record.kind)) fail("KIND_INVALID", "kind", "kind must be positive, negative or chaos");
+  if (!isNonEmptyString(record.requirement)) fail("REQUIREMENT_MISSING", "requirement", "requirement is required");
+  if (!Array.isArray(record.machines) || record.machines.length === 0 || !record.machines.every(isNonEmptyString)) fail("MACHINES_INVALID", "machines", "machines must be a non-empty array of machine ids");
+  if (!isIsoTimestamp(record.executed_at)) fail("EXECUTED_AT_INVALID", "executed_at", "executed_at must be an ISO timestamp");
+  if (!EVIDENCE_EXECUTORS.includes(record.executor)) fail("EXECUTOR_INVALID", "executor", "executor must be lead, human or agent");
+  if (record.commands !== undefined) {
+    const commandsValid = Array.isArray(record.commands) && record.commands.every((argv) => Array.isArray(argv) && argv.length > 0 && argv.every(isNonEmptyString));
+    if (!commandsValid) fail("COMMANDS_INVALID", "commands", "commands must be an array of argv arrays");
+  }
+  if (record.ledger_seq !== undefined) {
+    const valid = Array.isArray(record.ledger_seq) && record.ledger_seq.length === 2 && record.ledger_seq.every((value) => Number.isInteger(value) && value >= 0) && record.ledger_seq[0] <= record.ledger_seq[1];
+    if (!valid) fail("LEDGER_SEQ_INVALID", "ledger_seq", "ledger_seq must be [from, to] with from <= to");
+  }
+  if (record.artifacts !== undefined) {
+    const valid = Array.isArray(record.artifacts) && record.artifacts.every((artifact) => artifact !== null && typeof artifact === "object" && isArtifactSha(artifact.sha256) && Number.isInteger(artifact.bytes) && artifact.bytes >= 0);
+    if (!valid) fail("ARTIFACTS_INVALID", "artifacts", "artifacts must be [{sha256, bytes}]");
+  }
+  if (record.result === null || typeof record.result !== "object" || Array.isArray(record.result)) {
+    fail("RESULT_MISSING", "result", "result object is required");
+  } else {
+    // A record may carry the verdict at the top level or under a nested task object (the live restart evidence does the latter),
+    // because both are the same fact; what is not allowed is a result with no verdict anywhere.
+    const outcome = isNonEmptyString(record.result.outcome) ? record.result.outcome : (record.result.task !== null && typeof record.result.task === "object" && isNonEmptyString(record.result.task.outcome) ? record.result.task.outcome : "");
+    if (outcome === "") fail("RESULT_OUTCOME_MISSING", "result.outcome", "result.outcome (or result.task.outcome) is required");
+    if (record.result.assertions !== undefined && (record.result.assertions === null || typeof record.result.assertions !== "object" || Array.isArray(record.result.assertions))) {
+      fail("RESULT_ASSERTIONS_INVALID", "result.assertions", "result.assertions must be an object when present");
+    }
+  }
+  if (record.kind === "positive") {
+    if (!isNonEmptyString(record.task_id)) fail("TASK_ID_MISSING", "task_id", "a positive case must name the real task it ran");
+  } else if (record.task_id !== undefined && record.task_id !== null && !isNonEmptyString(record.task_id)) {
+    fail("TASK_ID_INVALID", "task_id", "task_id must be a string when present");
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** Counts by kind and version, for a release note or a gate summary. */
+export function summarizeEvidence(records) {
+  const byKind = {};
+  const byVersion = {};
+  const invalid = [];
+  for (const record of records) {
+    const verdict = validateEvidence(record);
+    if (!verdict.ok) {
+      invalid.push({ case: record?.case ?? null, errors: verdict.errors });
+      continue;
+    }
+    const version = record.version;
+    byKind[record.kind] = (byKind[record.kind] ?? 0) + 1;
+    byVersion[version] = (byVersion[version] ?? 0) + 1;
+  }
+  return { total: records.length, valid: records.length - invalid.length, invalid, byKind, byVersion };
+}

package/src/agent/agent.mjs

@@ -25,6 +25,10 @@ import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
 import { existsSync, mkdirSync, mkdtempSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { commitTaskChanges, createWorktree, listChangedFiles, producePatch, removeWorktree } from './worktree.mjs';
+import { describePatchArtifact } from './patch-artifact.mjs';
+import { ferryMaintenance, maintenancePaths } from './maintenance-ferry.mjs';
+import { authorizeWithGrant } from './grant-gate.mjs';
 import { tmpdir } from 'node:os';
 import { randomUUID , sign as signBytes } from 'node:crypto';
 
@@ -2581,6 +2585,8 @@ export function createAgent(options) {
       comparePolicy,
       pipeline,
       protocolViolations,
+      authorization = null,
+      workspace = null,
     } = context;
 
     const stdout = execution?.stdout ?? Buffer.alloc(0);
@@ -2603,6 +2609,11 @@ export function createAgent(options) {
 
     const envelope = {
       envelope_version: ENVELOPE_VERSION,
+      // v1.3.12-beta.3: how this execution was authorised -- 'grant' (operator, one execution), 'allow-list' (standing machine
+      // decision) or 'maintenance' (signed maintenance request). A reader can answer "who allowed this" without the ledger.
+      authorization: authorization ?? null,
+      // v1.3.13-beta.2: the copy this task ran on, and the patch it produced (evidence, not a promise).
+      workspace: workspace ?? null,
       task_id: offer.task_id,
       attempt: Number(offer.attempt) || 1,
       dedupe_key: offer.dedupe_key ?? '',
@@ -2925,6 +2936,9 @@ export function createAgent(options) {
     /** @type {string[]} */
     const warnings = [];
 
+    // Hoisted so the catch below can clean up a worktree even when the failure happened after creation.
+    let workspaceState = null;
+
     try {
       // ---- 3. capability gate (§6.1) -------------------------------------
       const writable = offer.write === true ? await isWritableProject(project) : true;
@@ -2957,7 +2971,27 @@ export function createAgent(options) {
       // `stages[0].command_argv` -- so this check covers the first stage and nothing else. Every
       // stage is checked below, before any of them runs; see the note there for why the second check
       // has to exist even though the plugin's pre-flight also checks every stage.
-      const allowed = matchAllowedCommand(commandArgv, allowedCommands);
+      /**
+       * v1.3.10-beta.3: the allow-list is a standing decision; a grant is a decision made now for exactly this argv.
+       * Ask the grant gate before falling through to the allow-list refusal, and never the other way round.
+       */
+      let allowed = matchAllowedCommand(commandArgv, allowedCommands);
+      let grantAuthorized = false;
+      if (allowed.allowed !== true && offer && typeof offer.grant === 'object' && offer.grant !== null) {
+        const gatePaths = maintenancePaths();
+        const gate = await authorizeWithGrant({
+          offer,
+          machineId: String(offer.machine_id ?? identity.machine_id ?? ''),
+          pinFile: gatePaths.pinFile,
+          usedFile: join(dirname(gatePaths.pinFile), 'grant-uses.json'),
+        });
+        if (gate.ok === true) { allowed = { allowed: true, ok: true, grant_id: gate.grantId }; grantAuthorized = true; }
+        else allowed = { ok: false, reason_code: gate.code ?? 'GRANT_REJECTED', detail: gate.message };
+      }
+      // One decision, two audiences: the gate decides whether to run, and the envelope records which decision it was.
+      const authorization = grantAuthorized
+        ? { provenance: 'grant', capability_id: allowed.grant_id ?? null, grant_id: allowed.grant_id ?? null }
+        : { provenance: 'allow-list' };
       if (!allowed.allowed) {
         log('warn', `refused ${offer.task_id}: ${allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED}`, { argv: commandArgv });
         await finish({
@@ -3036,6 +3070,50 @@ export function createAgent(options) {
        * a reduce that ran on half the inputs would produce a confident wrong answer, which is the failure this feature exists to
        * make impossible.
        */
+      /**
+       * v1.3.10-beta.2: a maintenance request is verified and carried by maintenance-ferry.mjs, not executed here. The
+       * agent has no privilege to run update/restart/diag, which is the point of the separation.
+       */
+      if (offer && typeof offer.maintenance === 'object' && offer.maintenance !== null) {
+        const ferryStarted = Date.now();
+        const ferriedRaw = await ferryMaintenance({ offer, machineId: String(offer.machine_id ?? identity.machine_id ?? '') });
+        // The ferry successful only means the runner wrote a result file; the runner itself may have failed. Reporting that
+        // as ok would tell the operator a restart/update happened when it did not.
+        const runnerOk = ferriedRaw.ok === true && ferriedRaw.result?.status === 'ok';
+        const ferried = runnerOk ? ferriedRaw : { ok: false, code: ferriedRaw.result?.code ?? ferriedRaw.code ?? 'MAINTENANCE_FAILED', message: ferriedRaw.result?.code ?? ferriedRaw.message ?? 'maintenance runner reported failure', requestId: ferriedRaw.requestId };
+        const stdoutText = JSON.stringify(ferried).slice(0, 64 * 1024);
+        const stderrText = ferried.ok ? '' : (ferried.message ?? ferried.code ?? 'maintenance failed');
+        // The envelope builder hashes and sizes the output; leaving any of these undefined makes canonicalisation fail
+        // with a JCS error and the task is reported as crashed after the maintenance action already ran.
+        const execution = {
+          exit_code: ferried.ok ? 0 : 1,
+          stdout: stdoutText,
+          stderr: stderrText,
+          stdout_sha256: sha256Hex(stdoutText),
+          stderr_sha256: sha256Hex(stderrText),
+          stdout_bytes: Buffer.byteLength(stdoutText, 'utf8'),
+          stderr_bytes: Buffer.byteLength(stderrText, 'utf8'),
+          duration_ms: Date.now() - ferryStarted,
+          timed_out: ferried.code === 'MAINTENANCE_RUNNER_TIMEOUT',
+        };
+        await finish({
+          offer,
+          cwdRel,
+          commandArgv,
+          anchorsBefore,
+          anchorsAfter: null,
+          execution,
+          authorization: { provenance: 'maintenance', capability_id: typeof offer.maintenance?.request_id === 'string' ? offer.maintenance.request_id : null },
+          status: ferried.ok ? 'ok' : 'failed',
+          refusalReason: ferried.ok ? null : 'MAINTENANCE_FAILED',
+          warnings,
+          startedAt,
+          endedAt: new Date().toISOString(),
+          protocolViolations: [],
+        });
+        return;
+      }
+
       let reduceEnv = null;
       if (Array.isArray(offer.reduce_inputs) && offer.reduce_inputs.length > 0) {
         try {
@@ -3080,10 +3158,34 @@ export function createAgent(options) {
         }
       }
 
+      /**
+       * v1.3.13-beta.2 (task model): run a workspace task in its own git worktree at the caller base_commit, then turn the
+       * result into a content-addressed patch. Created only after the allow-list/grant gate, so a refused task never leaves a
+       * tree behind; cleaned before the envelope is sent, so the reported evidence describes a finished state.
+       */
+      if (offer.workspace !== null && offer.workspace !== undefined) {
+        if (offer.workspace.kind !== 'worktree') {
+          await finish({ offer, cwdRel, commandArgv, anchorsBefore, anchorsAfter: null, execution: null, status: 'refused', refusalReason: 'WORKSPACE_UNSUPPORTED', warnings: ['WORKSPACE_UNSUPPORTED: only worktree workspaces exist'], startedAt: new Date().toISOString(), endedAt: new Date().toISOString() });
+          return;
+        }
+        const workspaceDirName = String(offer.task_id).replace(/[^A-Za-z0-9._-]/g, '_');
+        const worktreeDir = join(project, '.w2m-worktrees', workspaceDirName);
+        const created = await createWorktree({ repoDir: project, baseCommit: offer.workspace.base_commit, worktreeDir });
+        if (created.ok !== true) {
+          log('warn', `refused ${offer.task_id}: WORKSPACE_CREATE_FAILED`, { code: created.code });
+          await finish({ offer, cwdRel, commandArgv, anchorsBefore, anchorsAfter: null, execution: null, status: 'refused', refusalReason: 'WORKSPACE_CREATE_FAILED', warnings: ['WORKSPACE_CREATE_FAILED: ' + String(created.code ?? 'unknown')], startedAt: new Date().toISOString(), endedAt: new Date().toISOString(), protocolViolations: ['workspace could not be created'] });
+          return;
+        }
+        workspaceState = { worktreeDir, baseCommit: offer.workspace.base_commit, produce: offer.workspace.produce ?? 'patch', relCwd: '.w2m-worktrees/' + workspaceDirName };
+        log('info', `${offer.task_id} workspace ${workspaceState.baseCommit.slice(0, 12)} at ${workspaceState.relCwd}`);
+      }
+
       for (const stage of plannedStages) {
-        const stageAllowed = matchAllowedCommand(stage.command_argv, allowedCommands);
+        // v1.3.10-beta.6: a grant that authorised step 5 covers the whole task, but only for the argv it signed.
+      const stageAllowed = grantAuthorized ? { allowed: true, ok: true } : matchAllowedCommand(stage.command_argv, allowedCommands);
         if (stageAllowed.allowed) continue;
         const code = stageAllowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED;
+        if (workspaceState !== null) { try { await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir }); } catch { /* best effort */ } }
         log('warn', `refused ${offer.task_id}: ${code} at stage ${stage.index}`, {
           argv: stage.command_argv,
         });
@@ -3124,7 +3226,13 @@ export function createAgent(options) {
       for (const stage of plannedStages) {
         heartbeat.setPhase('running', 50);
 
-        const stageCwdOutcome = resolveProjectCwd(project, stage.cwd_rel, { allowOutside: offer.cwd_outside_project === true });
+        // A workspace task runs in its own copy: an explicit stage cwd is relative to that copy, and the default is its root.
+      const workspaceRel = workspaceState === null
+        ? null
+        : (stage.cwd_rel === undefined || stage.cwd_rel === cwdRel || stage.cwd_rel === '.')
+          ? workspaceState.relCwd
+          : workspaceState.relCwd + '/' + normalizeRelPath(stage.cwd_rel);
+      const stageCwdOutcome = resolveProjectCwd(project, workspaceRel ?? stage.cwd_rel, { allowOutside: offer.cwd_outside_project === true });
         if (!stageCwdOutcome.ok) {
           // A stage whose cwd is outside the project is a refusal of the whole chain: continuing
           // would run later stages against a working directory the caller never asked for.
@@ -3301,6 +3409,33 @@ export function createAgent(options) {
       if (execution?.timed_out) log('warn', `${offer.task_id} timed out after ${offer.timeout_ms}ms`);
       if (execution?.cancelled) log('warn', `${offer.task_id} was cancelled`);
 
+      let workspaceEvidence = null;
+      if (workspaceState !== null) {
+        const commit = await commitTaskChanges({ worktreeDir: workspaceState.worktreeDir, message: 'task ' + offer.task_id });
+        const patch = await producePatch({ worktreeDir: workspaceState.worktreeDir, baseCommit: workspaceState.baseCommit });
+        const changed = await listChangedFiles({ worktreeDir: workspaceState.worktreeDir, baseCommit: workspaceState.baseCommit });
+        const artifact = patch.ok === true ? describePatchArtifact({ patch: patch.patch, baseCommit: workspaceState.baseCommit, headCommit: commit.ok === true ? (commit.headCommit ?? null) : null, filesChanged: changed.ok === true ? changed.files : [] }) : null;
+        let patchSha = null;
+        if (patch.ok === true && typeof patch.patch === 'string' && patch.patch.trim() !== '') {
+          const sha = sha256Hex(patch.patch);
+          const uploaded = await putBlobBytes(sha, patch.patch);
+          if (uploaded.ok === true) patchSha = sha;
+          else warnings.push('PATCH_UPLOAD_FAILED');
+        }
+        const removed = await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir });
+        if (removed.ok !== true) warnings.push('WORKTREE_CLEANUP_FAILED');
+        workspaceEvidence = {
+          kind: 'worktree',
+          base_commit: workspaceState.baseCommit,
+          produce: workspaceState.produce,
+          head_commit: commit.ok === true ? (commit.headCommit ?? null) : null,
+          changed_files: artifact !== null && artifact.ok === true ? artifact.filesChanged : [],
+          patch_sha256: patchSha,
+          patch_bytes: typeof patch.patch === 'string' ? Buffer.byteLength(patch.patch, 'utf8') : 0,
+          cleaned: removed.ok === true,
+        };
+      }
+
       const anchorsAfter = await safeAnchors(warnings);
       const status = execution ? classifyExit(execution) : (protocolViolations.length > 0 ? 'refused' : 'unverifiable');
 
@@ -3311,6 +3446,8 @@ export function createAgent(options) {
         anchorsBefore,
         anchorsAfter,
         execution,
+        authorization,
+        workspace: workspaceEvidence,
         blobSha256: lastBlobSha256,
         status,
         refusalReason: null,
@@ -3333,6 +3470,7 @@ export function createAgent(options) {
       // Never leave a claimed task unspooled: emit a crashed envelope so the
       // relay can account for it instead of waiting for a lease to expire.
       log('error', `error while handling ${offer.task_id}`, { error: error?.message ?? String(error) });
+      if (workspaceState !== null) { try { await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir }); } catch { /* best effort */ } }
       try {
         const envelope = makeEnvelope({
           offer,

package/src/agent/grant-gate.mjs

@@ -0,0 +1,89 @@
+/**
+ * Agent-side grant gate (M2, v1.3.10-beta.3 slice).
+ *
+ * The allow-list is a standing decision; a grant is a decision made now. This gate is what the agent asks before it falls
+ * through to the allow-list refusal: is there a valid signed grant for exactly this argv, on this machine, for this task,
+ * still inside its window, and not already spent?
+ *
+ * Verification is delegated to src/maintenance/grant.mjs; this file owns the decision's state (which grants were used) and
+ * the operator pin handling (first contact pins, later keys must rotate).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { verifyGrant } from '../maintenance/grant.mjs';
+import { createPinStore } from '../maintenance/operator-key.mjs';
+
+/**
+ * @param {object} options
+ * @param {object} options.offer the task offer
+ * @param {string} options.machineId
+ * @param {string} options.pinFile operator pin store path
+ * @param {string} [options.usedFile] persisted grant uses (grant_id -> count, plus nonces)
+ * @param {() => number} [options.now]
+ * @returns {Promise<{ok: true, grantId: string, used: number} | {ok: false, code: string, message: string, detail?: object}>}
+ */
+export async function authorizeWithGrant(options) {
+  const { offer, machineId, pinFile, usedFile, now = () => Date.now() } = options;
+  const grant = offer?.grant;
+  if (grant === null || typeof grant !== 'object') return { ok: false, code: 'GRANT_MISSING', message: 'no grant on the offer' };
+
+  const store = createPinStore(pinFile);
+  let pins;
+  try { pins = store.load(); } catch (error) { return { ok: false, code: error?.code ?? 'PINS_CORRUPT', message: error?.message ?? 'pin store unreadable' }; }
+  if (pins.pinned === null) {
+    if (typeof offer.operator_key?.public_key_pem !== 'string') return { ok: false, code: 'GRANT_NO_PINNED_KEY', message: 'no operator key is pinned and none was supplied' };
+    try {
+      store.pinFromRegistration({ protocol: 'w2m-operator-key/v1', key_id: offer.operator_key.key_id, public_key_pem: offer.operator_key.public_key_pem, created_at: offer.operator_key.created_at });
+      pins = store.load();
+    } catch (error) {
+      return { ok: false, code: error?.code ?? 'GRANT_PIN_FAILED', message: error?.message ?? 'operator key could not be pinned' };
+    }
+  }
+
+  const used = readUsed(usedFile);
+  const verified = verifyGrant(grant, {
+    publicKeyPem: pins.pinned.public_key_pem,
+    expectedKeyId: pins.pinned.key_id,
+    nowMs: now(),
+    machineId,
+    taskId: typeof offer.task_id === 'string' ? offer.task_id : null,
+    argv: Array.isArray(offer.command_argv) ? offer.command_argv : [],
+    usedGrantIds: new Set(Object.keys(used.grants)),
+    usedNonces: new Set(used.nonces),
+    usedCount: used.grants[grant.grant_id] ?? 0,
+    isRevoked: (keyId) => store.isRevoked(keyId),
+    policy: { mode: offer.mode, cwd_rel: offer.cwd_rel, write: offer.write === true, write_scope: offer.write_scope },
+  });
+  if (verified.ok !== true) return { ok: false, code: verified.code, message: verified.detail?.message ?? 'grant refused', detail: verified.detail };
+
+  used.grants[grant.grant_id] = (used.grants[grant.grant_id] ?? 0) + 1;
+  used.nonces = [...used.nonces, grant.nonce].slice(-500);
+  // Fail closed: the use ledger is what makes a single-use grant single-use, so an unwritable ledger must refuse the task
+  // rather than run it unrecorded (and rather than crash the whole handler). Seen on a real host where the maintenance state
+  // directory was root-owned but the agent ran unprivileged.
+  try {
+    writeUsed(usedFile, used);
+  } catch (error) {
+    return { ok: false, code: 'GRANT_LEDGER_UNAVAILABLE', message: 'the grant use ledger cannot be written: ' + String(error?.message ?? error) };
+  }
+  return { ok: true, grantId: grant.grant_id, used: used.grants[grant.grant_id] };
+}
+
+function readUsed(file) {
+  if (typeof file !== 'string' || file === '' || !existsSync(file)) return { grants: {}, nonces: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return { grants: parsed.grants && typeof parsed.grants === 'object' ? parsed.grants : {}, nonces: Array.isArray(parsed.nonces) ? parsed.nonces : [] };
+  } catch {
+    // A corrupt use ledger must not silently reset counts: that would make a spent grant usable again.
+    return { grants: { __corrupt__: 1 }, nonces: [] };
+  }
+}
+
+function writeUsed(file, used) {
+  if (typeof file !== 'string' || file === '') return;
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  writeFileSync(tmp, JSON.stringify({ protocol: 'w2m-grant-uses/v1', ...used }, null, 2) + '\n', 'utf8');
+  renameSync(tmp, file);
+}

package/src/agent/maintenance-ferry.mjs

@@ -0,0 +1,111 @@
+/**
+ * Agent-side maintenance ferry (v1.3.10-beta.2, M1).
+ *
+ * The agent is not privileged enough to run update/restart/diag, and it should not be: it carries the signed request to the
+ * queue the root runner watches, waits for that runner's result file, and hands the result back to the task. Everything
+ * about verification lives here so the agent file only has to call one function.
+ *
+ * Failure is a value, not an exception: the agent needs to report "refused because GRANT..." as a task result, and a thrown
+ * error would lose the reason.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { verifyRequest } from '../maintenance/protocol.mjs';
+import { createPinStore } from '../maintenance/operator-key.mjs';
+
+export function maintenancePaths(env = process.env, platform = process.platform) {
+  if (platform === 'win32') {
+    return {
+      queueDir: env.W2M_MAINTENANCE_QUEUE ?? 'C:\\ProgramData\\w2m\\maintenance\\queue',
+      doneDir: env.W2M_MAINTENANCE_DONE ?? 'C:\\ProgramData\\w2m\\maintenance\\done',
+      pinFile: env.W2M_MAINTENANCE_PINS ?? 'C:\\ProgramData\\w2m\\maintenance\\operator-pins.json',
+    };
+  }
+  return {
+    queueDir: env.W2M_MAINTENANCE_QUEUE ?? '/var/lib/w2m/maintenance/queue',
+    doneDir: env.W2M_MAINTENANCE_DONE ?? '/var/lib/w2m/maintenance/done',
+    pinFile: env.W2M_MAINTENANCE_PINS ?? '/var/lib/w2m/maintenance/operator-pins.json',
+  };
+}
+
+/**
+ * Carry one offer's maintenance request to the root runner and return its result.
+ *
+ * @param {object} options
+ * @param {object} options.offer the task offer (must carry maintenance and may carry operator_key)
+ * @param {string} options.machineId this machine's id
+ * @param {string} [options.queueDir]
+ * @param {string} [options.doneDir]
+ * @param {string} [options.pinFile]
+ * @param {number} [options.timeoutMs]
+ * @param {() => number} [options.now]
+ * @param {(ms: number) => Promise<void>} [options.sleep]
+ * @returns {Promise<{ok: true, result: object, requestId: string} | {ok: false, code: string, message: string, requestId: string|null}>}
+ */
+export async function ferryMaintenance(options) {
+  const {
+    offer,
+    machineId,
+    timeoutMs = 120_000,
+    now = () => Date.now(),
+    sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+  } = options;
+  const paths = maintenancePaths(options.env, options.platform);
+  const queueDir = options.queueDir ?? paths.queueDir;
+  const doneDir = options.doneDir ?? paths.doneDir;
+  const pinFile = options.pinFile ?? paths.pinFile;
+  const request = offer?.maintenance;
+  const requestId = typeof request?.request_id === 'string' ? request.request_id : null;
+  const fail = (code, message) => ({ ok: false, code, message, requestId });
+
+  if (requestId === null) return fail('MAINTENANCE_BAD_SHAPE', 'offer carries no maintenance.request_id');
+  const store = createPinStore(pinFile);
+  let pins;
+  try {
+    pins = store.load();
+  } catch (error) {
+    return fail(error?.code ?? 'PINS_CORRUPT', error?.message ?? 'operator pin store is unreadable');
+  }
+  if (pins.pinned === null) {
+    if (typeof offer.operator_key?.public_key_pem !== 'string') return fail('MAINTENANCE_NO_PINNED_KEY', 'no pinned operator key and none supplied with the request');
+    try {
+      store.pinFromRegistration({ protocol: 'w2m-operator-key/v1', key_id: offer.operator_key.key_id, public_key_pem: offer.operator_key.public_key_pem, created_at: offer.operator_key.created_at });
+      pins = store.load();
+    } catch (error) {
+      return fail(error?.code ?? 'MAINTENANCE_PIN_FAILED', error?.message ?? 'operator key could not be pinned');
+    }
+  }
+  const verified = verifyRequest(request, {
+    publicKeyPem: pins.pinned.public_key_pem,
+    expectedKeyId: pins.pinned.key_id,
+    expectedMachineId: String(machineId ?? ''),
+    nowMs: now(),
+    isRevoked: (keyId) => store.isRevoked(keyId),
+  });
+  if (verified.ok !== true) return fail(verified.code, verified.detail?.message ?? 'maintenance request refused');
+
+  const requestFile = join(queueDir, String(requestId) + '.json');
+  const doneFile = join(doneDir, encodeURIComponent(String(requestId)) + '.json');
+  try {
+    mkdirSync(queueDir, { recursive: true });
+    mkdirSync(doneDir, { recursive: true });
+    const tmp = requestFile + '.tmp-' + process.pid;
+    writeFileSync(tmp, JSON.stringify(request), 'utf8');
+    renameSync(tmp, requestFile);
+  } catch (error) {
+    return fail('MAINTENANCE_QUEUE_UNAVAILABLE', error?.message ?? 'the maintenance queue directory is not writable');
+  }
+
+  const deadline = now() + Math.max(1_000, Number(timeoutMs) || 120_000);
+  while (now() < deadline) {
+    if (existsSync(doneFile)) {
+      try {
+        return { ok: true, result: JSON.parse(readFileSync(doneFile, 'utf8')), requestId };
+      } catch (error) {
+        return fail('MAINTENANCE_RESULT_UNREADABLE', error?.message ?? 'the runner wrote an unreadable result');
+      }
+    }
+    await sleep(500);
+  }
+  return fail('MAINTENANCE_RUNNER_TIMEOUT', 'the root runner did not report within the timeout');
+}