@twinsearth/w2m-dsh-plugin 2.1.11 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "2.1.11",
+  "version": "2.2.1",
   "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": {
@@ -71,7 +71,7 @@
     "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/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/exec-capability.test.mjs test/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.test.mjs test/npm-update.test.mjs test/agent-start-nonblocking.test.mjs test/fleet-chat-capture.test.mjs test/capture-route.test.mjs test/update-resolver.test.mjs test/agent-identity-safe.test.mjs test/re-pair-stale-token.test.mjs test/gpw-folder-policy.test.mjs test/gpw-activation.test.mjs test/gpw-hardening.test.mjs test/gpw-tamper-gate.test.mjs test/gpw-persistence.test.mjs test/gpw-colors.test.mjs test/gpw-recent-fold.test.mjs test/gpw-auto-approve.test.mjs test/joint-dev-dispatch.test.mjs test/joint-dev-loop.test.mjs test/joint-dev-audit.test.mjs test/joint-dev-redline.test.mjs test/relay-redline-guard.test.mjs test/relay-p0-projection.test.mjs test/guarded-dispatch.test.mjs test/p0-single-matcher.test.mjs test/path-policy.test.mjs test/path-policy-fs.test.mjs test/gpw-inheritance-table.test.mjs test/gpw-policy-adapter.test.mjs test/target-policy.test.mjs test/relay-redline-audit.test.mjs test/relay-repair-ledger.test.mjs test/relay-purge-blobs.test.mjs test/relay-scrub.test.mjs test/joint-dev-plan-store.test.mjs test/relay-basepath-blobs.test.mjs test/operator-token.test.mjs test/relay-health-capabilities.test.mjs test/joint-relay-dispatch.test.mjs test/operator-token-route.test.mjs test/relay-scrub-task-projection.test.mjs test/operator-key-approval.test.mjs test/relay-offer-journal.test.mjs test/joint-r5-wiring.test.mjs test/p1-hardening.test.mjs test/joint-merge-engine.test.mjs test/artifact-ref-dir-sink.test.mjs test/chat-sticker-guard.test.mjs test/relay-task-progress.test.mjs test/gpw-modes.test.mjs test/joint-cli.test.mjs test/joint-command-hash.test.mjs test/joint-dispatch-audit.test.mjs test/tools-cancel-auth.test.mjs test/fleet-mirror.test.mjs test/sink-git-ssh.test.mjs test/agent-sse-watchdog.test.mjs test/version-gate.test.mjs test/joint-merge-cli.test.mjs test/joint-progress.test.mjs test/project-room-truncation.test.mjs test/chat-crypto-aad.test.mjs test/agent-artifact-delivery.test.mjs test/dataplane-sink-route.test.mjs test/artifact-sink-e2e.test.mjs test/project-room-persistence.test.mjs test/project-room-disk-persistence.test.mjs test/project-stream-route.test.mjs test/chat-v2-gate.test.mjs test/xiangqi.test.mjs test/xfer-foundation.test.mjs test/xfer-ferry.test.mjs test/xfer-publish.test.mjs test/xfer-want-block.test.mjs test/p2p-cipher-diag.test.mjs test/chacha-fallback.test.mjs test/fleet-binding.test.mjs test/xfer-channel.test.mjs test/p2p-race.test.mjs test/path-scheduler.test.mjs test/transport.test.mjs test/iroh-sidecar.test.mjs test/discovery.test.mjs test/p2p-rtt.test.mjs test/artifact-ref-v3.test.mjs test/xfer-recovery.test.mjs test/xfer-router.test.mjs test/remote-s2-capture.test.mjs test/view-capture.test.mjs test/view-frame-channel.test.mjs test/remote-view-route.test.mjs test/remote-media.test.mjs test/view-session-key.test.mjs test/remote-requests.test.mjs test/relay-target.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/exec-capability.test.mjs test/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.test.mjs test/npm-update.test.mjs test/agent-start-nonblocking.test.mjs test/fleet-chat-capture.test.mjs test/capture-route.test.mjs test/update-resolver.test.mjs test/agent-identity-safe.test.mjs test/re-pair-stale-token.test.mjs test/gpw-folder-policy.test.mjs test/gpw-activation.test.mjs test/gpw-hardening.test.mjs test/gpw-tamper-gate.test.mjs test/gpw-persistence.test.mjs test/gpw-colors.test.mjs test/gpw-recent-fold.test.mjs test/gpw-auto-approve.test.mjs test/joint-dev-dispatch.test.mjs test/joint-dev-loop.test.mjs test/joint-dev-audit.test.mjs test/joint-dev-redline.test.mjs test/relay-redline-guard.test.mjs test/relay-p0-projection.test.mjs test/guarded-dispatch.test.mjs test/p0-single-matcher.test.mjs test/path-policy.test.mjs test/path-policy-fs.test.mjs test/gpw-inheritance-table.test.mjs test/gpw-policy-adapter.test.mjs test/target-policy.test.mjs test/relay-redline-audit.test.mjs test/relay-repair-ledger.test.mjs test/relay-purge-blobs.test.mjs test/relay-scrub.test.mjs test/joint-dev-plan-store.test.mjs test/relay-basepath-blobs.test.mjs test/operator-token.test.mjs test/relay-health-capabilities.test.mjs test/joint-relay-dispatch.test.mjs test/operator-token-route.test.mjs test/relay-scrub-task-projection.test.mjs test/operator-key-approval.test.mjs test/relay-offer-journal.test.mjs test/joint-r5-wiring.test.mjs test/p1-hardening.test.mjs test/joint-merge-engine.test.mjs test/artifact-ref-dir-sink.test.mjs test/chat-sticker-guard.test.mjs test/relay-task-progress.test.mjs test/gpw-modes.test.mjs test/joint-cli.test.mjs test/joint-command-hash.test.mjs test/joint-dispatch-audit.test.mjs test/tools-cancel-auth.test.mjs test/fleet-mirror.test.mjs test/sink-git-ssh.test.mjs test/agent-sse-watchdog.test.mjs test/version-gate.test.mjs test/joint-merge-cli.test.mjs test/joint-progress.test.mjs test/project-room-truncation.test.mjs test/chat-crypto-aad.test.mjs test/agent-artifact-delivery.test.mjs test/dataplane-sink-route.test.mjs test/artifact-sink-e2e.test.mjs test/project-room-persistence.test.mjs test/project-room-disk-persistence.test.mjs test/project-stream-route.test.mjs test/chat-v2-gate.test.mjs test/xiangqi.test.mjs test/xfer-foundation.test.mjs test/xfer-ferry.test.mjs test/xfer-publish.test.mjs test/xfer-want-block.test.mjs test/p2p-cipher-diag.test.mjs test/chacha-fallback.test.mjs test/fleet-binding.test.mjs test/fleet-home.test.mjs test/fleet-config.test.mjs test/fleet-config-route.test.mjs test/xfer-channel.test.mjs test/p2p-race.test.mjs test/path-scheduler.test.mjs test/transport.test.mjs test/iroh-sidecar.test.mjs test/discovery.test.mjs test/p2p-rtt.test.mjs test/artifact-ref-v3.test.mjs test/xfer-recovery.test.mjs test/xfer-router.test.mjs test/remote-s2-capture.test.mjs test/view-capture.test.mjs test/view-frame-channel.test.mjs test/remote-view-route.test.mjs test/remote-media.test.mjs test/view-session-key.test.mjs test/remote-requests.test.mjs test/relay-target.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",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "2.1.11",
+  "version": "2.2.1",
   "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/plugin/fleet-binding.mjs

@@ -39,6 +39,28 @@ export function shouldRejoin({ token, fleetId, fleetKey, expectedFleetId = null
   return typeof expectedFleetId === 'string' && expectedFleetId !== '' && fleetId !== expectedFleetId;
 }
 
+/**
+ * Choose the key a start actually binds with.
+ *
+ * `fleetKeyPolicy: 'home'` (the default in 2.2.1) is the "the leaver returns, nobody else moves"
+ * rule: a machine that has been in a fleet for this account uses that fleet's key again, even when
+ * the freshly derived account key differs. `'account'` is the v2.2.0 opt-in that always follows the
+ * signed-in account, and `'config'` is the explicit operator pin.
+ *
+ * @param {{configured?: string|null, account?: string|null, home?: string|null, policy?: string}} input
+ * @returns {{fleetKey: string|null, source: 'home'|'account'|'config'|null}}
+ */
+export function selectFleetKey({ configured = null, account = null, home = null, policy = 'home' } = {}) {
+  const hasConfig = typeof configured === 'string' && configured.trim() !== '';
+  const hasAccount = typeof account === 'string' && account.trim() !== '';
+  const hasHome = typeof home === 'string' && home.trim() !== '';
+  if (policy === 'config' && hasConfig) return { fleetKey: configured, source: 'config' };
+  if (policy === 'home' && hasHome) return { fleetKey: home, source: 'home' };
+  if (hasAccount) return { fleetKey: account, source: 'account' };
+  if (hasConfig) return { fleetKey: configured, source: 'config' };
+  return { fleetKey: null, source: null };
+}
+
 /**
  * Read this machine's relay record and classify its fleet binding.
  *

package/src/plugin/fleet-config-route.mjs

@@ -0,0 +1,130 @@
+/**
+ * `/api/w2m/fleet-config` (v2.2.1): the settings-page half of the fleet pin.
+ *
+ *   GET  /api/w2m/fleet-config
+ *        → {ok, configured, policy, fleet_id, fingerprint, path}
+ *   POST /api/w2m/fleet-config {action:'preview', fleet_key, expected_fleet_id?}
+ *        → {ok, fleet_id, fleet_key_fingerprint, matches_expected}   (writes nothing)
+ *   POST /api/w2m/fleet-config {action:'save', fleet_key, expected_fleet_id?}
+ *        → {ok, configured, policy, fleet_id, fingerprint, path, backup, restart_required}
+ *
+ * The raw key is never returned. `preview` is the confirmation step: the page shows the derived
+ * fleet id, the operator compares it with the expected id, and only then does `save` replace the
+ * file (with a timestamped backup and rollback).
+ */
+
+import { fingerprintOf } from './operator-token.mjs';
+import { readFleetConfig, writeFleetConfig } from './fleet-config.mjs';
+
+export const FLEET_CONFIG_ROUTE_PATH = '/api/w2m/fleet-config';
+const NO_STORE = { 'cache-control': 'no-store' };
+
+/**
+ * @param {object} ctx Cordis context.
+ * @param {{file?: string|(() => string|null)}} [deps]
+ * @returns {{mounted: boolean, reason: string|null}}
+ */
+export function registerFleetConfigRoute(ctx, deps = {}) {
+  const status = { mounted: false, reason: 'the host has no Connection service' };
+  if (typeof ctx?.inject !== 'function') return status;
+  ctx.inject(['connection'], (webCtx) => {
+    const registry = webCtx?.connection?.fetch;
+    if (registry === undefined || typeof registry.register !== 'function') {
+      status.reason = 'the connection service carries no fetch registry';
+      return;
+    }
+    const fileOf = () => (typeof deps.file === 'function' ? deps.file() : deps.file ?? null);
+
+    registry.register({
+      path: FLEET_CONFIG_ROUTE_PATH,
+      methods: ['GET', 'POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        const file = fileOf();
+        if (typeof file !== 'string' || file === '') {
+          return Response.json({ ok: false, code: 'FLEET_CONFIG_NO_STATE', error: 'no state directory is known' }, { status: 503, headers: NO_STORE });
+        }
+
+        if (request.method === 'GET') {
+          const read = readFleetConfig(file);
+          if (read.ok !== true) {
+            return Response.json({ ok: false, code: read.code, error: read.error, path: read.path }, { status: 500, headers: NO_STORE });
+          }
+          const config = read.config;
+          return Response.json({
+            ok: true,
+            configured: config !== null,
+            policy: config?.policy ?? null,
+            fleet_id: config?.fleetId ?? null,
+            fingerprint: config === null ? null : fingerprintOf(config.fleetKey),
+            updated_at: config?.updatedAt ?? null,
+            path: file,
+            source: config === null ? 'none' : 'file',
+          }, { headers: NO_STORE });
+        }
+
+        let body = null;
+        try { body = await request.json(); } catch { /* refused below */ }
+        if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+          return Response.json({ ok: false, code: 'FLEET_CONFIG_BAD_BODY', error: 'send a JSON object' }, { status: 400, headers: NO_STORE });
+        }
+        const action = body.action;
+        if (action !== 'preview' && action !== 'save') {
+          return Response.json({ ok: false, code: 'FLEET_CONFIG_BAD_ACTION', error: 'action must be preview or save' }, { status: 400, headers: NO_STORE });
+        }
+        const fleetKey = typeof body.fleet_key === 'string' ? body.fleet_key.trim() : '';
+        if (fleetKey === '') {
+          return Response.json({ ok: false, code: 'FLEET_CONFIG_KEY_REQUIRED', error: 'fleet_key is required' }, { status: 400, headers: NO_STORE });
+        }
+        const { planJoin } = await import('../chatops/fleet-join.mjs');
+        const plan = planJoin({ fleetKeyEncoded: fleetKey });
+        if (plan.ok !== true) {
+          return Response.json({ ok: false, code: plan.reason, error: plan.text }, { status: 400, headers: NO_STORE });
+        }
+        const expected = typeof body.expected_fleet_id === 'string' ? body.expected_fleet_id.trim().toLowerCase() : '';
+        const matchesExpected = expected === '' ? null : expected === plan.fleetId;
+        if (action === 'preview') {
+          return Response.json({
+            ok: true,
+            action: 'preview',
+            fleet_id: plan.fleetId,
+            fleet_key_fingerprint: fingerprintOf(fleetKey),
+            matches_expected: matchesExpected,
+          }, { headers: NO_STORE });
+        }
+        if (matchesExpected === false) {
+          return Response.json({
+            ok: false,
+            code: 'FLEET_CONFIG_FLEET_ID_MISMATCH',
+            error: 'the key derives a different fleet_id than the expected one',
+            fleet_id: plan.fleetId,
+            expected_fleet_id: expected,
+          }, { status: 409, headers: NO_STORE });
+        }
+
+        const written = writeFleetConfig(file, {
+          fleetKey,
+          fleetId: plan.fleetId,
+          policy: 'config',
+        });
+        if (written.ok !== true) {
+          return Response.json({ ok: false, code: written.code, error: written.error, path: written.path }, { status: 500, headers: NO_STORE });
+        }
+        return Response.json({
+          ok: true,
+          action: 'save',
+          configured: true,
+          policy: 'config',
+          fleet_id: plan.fleetId,
+          fingerprint: fingerprintOf(fleetKey),
+          path: written.path,
+          backup: written.backup,
+          restart_required: true,
+        }, { headers: NO_STORE });
+      },
+    });
+    status.mounted = true;
+    status.reason = null;
+  });
+  return status;
+}

package/src/plugin/fleet-config.mjs

@@ -0,0 +1,183 @@
+/**
+ * The operator-facing fleet pin, stored beside `device.json`.
+ *
+ * `cordis.patch.yml` is a profile layer, and asking an operator to hand-edit it is how a working
+ * DSH gets broken. This file is the supported alternative: the settings page writes it atomically,
+ * the plugin reads it at startup, and the profile YAML is never touched.
+ *
+ * The file contains an encoded fleet key, which is a credential: mode 0600 where the platform
+ * honours it, and the route only ever returns a fingerprint. Every write makes a timestamped
+ * backup first; a failed validation or rename restores that backup instead of leaving a half-written
+ * pin that changes the next boot.
+ */
+
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { deviceFilePath } from '../agent/identity.mjs';
+
+export const FLEET_CONFIG_FILE = 'fleet-config.json';
+export const FLEET_CONFIG_VERSION = 1;
+export const FLEET_CONFIG_POLICIES = Object.freeze(['config', 'home', 'account']);
+
+const MAX_KEY_LENGTH = 4096;
+const FLEET_ID_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Resolve the pin file the same way the plugin resolves `device.json`.
+ *
+ * @param {string|null|undefined} stateDir An explicit state directory, or null/undefined.
+ * @returns {string|null}
+ */
+export function fleetConfigPathFor(stateDir) {
+  if (typeof stateDir === 'string' && stateDir.trim() !== '') {
+    return join(stateDir.trim(), FLEET_CONFIG_FILE);
+  }
+  try {
+    return join(dirname(deviceFilePath({})), FLEET_CONFIG_FILE);
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string|null} deviceFile */
+export function fleetConfigPathBeside(deviceFile) {
+  return typeof deviceFile === 'string' && deviceFile !== '' ? join(dirname(deviceFile), FLEET_CONFIG_FILE) : null;
+}
+
+/**
+ * Read the pin. A missing file is "not configured", not an error.
+ *
+ * @param {string|null} file
+ * @returns {{ok: true, config: null, path: string|null}
+ *   | {ok: true, config: {fleetKey: string, policy: string, fleetId: string, updatedAt: string}, path: string}
+ *   | {ok: false, code: string, error: string, path: string|null}}
+ */
+export function readFleetConfig(file) {
+  if (file === null || file === undefined || file === '') return { ok: true, config: null, path: null };
+  if (!existsSync(file)) return { ok: true, config: null, path: file };
+
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (error) {
+    return { ok: false, code: 'FLEET_CONFIG_UNREADABLE', error: error instanceof Error ? error.message : String(error), path: file };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return { ok: false, code: 'FLEET_CONFIG_CORRUPT', error: `not valid JSON: ${error instanceof Error ? error.message : String(error)}`, path: file };
+  }
+  if (parsed === null || typeof parsed !== 'object' || parsed.version !== FLEET_CONFIG_VERSION) {
+    return { ok: false, code: 'FLEET_CONFIG_CORRUPT', error: `expected version ${FLEET_CONFIG_VERSION}`, path: file };
+  }
+  const fleetKey = typeof parsed.fleet_key === 'string' ? parsed.fleet_key.trim() : '';
+  const policy = typeof parsed.fleet_key_policy === 'string' ? parsed.fleet_key_policy.trim() : '';
+  const fleetId = typeof parsed.fleet_id === 'string' ? parsed.fleet_id.trim().toLowerCase() : '';
+  if (fleetKey === '' || fleetKey.length > MAX_KEY_LENGTH) {
+    return { ok: false, code: 'FLEET_CONFIG_CORRUPT', error: 'fleet_key is missing or too long', path: file };
+  }
+  if (!FLEET_CONFIG_POLICIES.includes(policy)) {
+    return { ok: false, code: 'FLEET_CONFIG_CORRUPT', error: `fleet_key_policy must be one of ${FLEET_CONFIG_POLICIES.join(', ')}`, path: file };
+  }
+  if (!FLEET_ID_RE.test(fleetId)) {
+    return { ok: false, code: 'FLEET_CONFIG_CORRUPT', error: 'fleet_id is not a 64-hex SHA-256', path: file };
+  }
+  return {
+    ok: true,
+    config: {
+      fleetKey,
+      policy,
+      fleetId,
+      updatedAt: typeof parsed.updated_at === 'string' ? parsed.updated_at : '',
+    },
+    path: file,
+  };
+}
+
+/**
+ * Write a validated pin with a backup and rollback.
+ *
+ * Validation is repeated on the temporary file before it replaces the live one, so a write that
+ * somehow serialised wrong cannot become the next boot's configuration.
+ *
+ * @param {string|null} file
+ * @param {{fleetKey: string, fleetId: string, policy?: string, now?: number}} input
+ * @returns {{ok: true, path: string, backup: string|null}
+ *   | {ok: false, code: string, error: string, path: string|null}}
+ */
+export function writeFleetConfig(file, input) {
+  if (file === null || file === undefined || file === '') {
+    return { ok: false, code: 'FLEET_CONFIG_NO_PATH', error: 'no state directory is known', path: null };
+  }
+  const fleetKey = typeof input?.fleetKey === 'string' ? input.fleetKey.trim() : '';
+  const fleetId = typeof input?.fleetId === 'string' ? input.fleetId.trim().toLowerCase() : '';
+  const policy = typeof input?.policy === 'string' ? input.policy : 'config';
+  if (fleetKey === '' || fleetKey.length > MAX_KEY_LENGTH) {
+    return { ok: false, code: 'FLEET_CONFIG_BAD_KEY', error: 'fleet key is empty or too long', path: file };
+  }
+  if (!FLEET_ID_RE.test(fleetId)) {
+    return { ok: false, code: 'FLEET_CONFIG_BAD_FLEET_ID', error: 'fleet id is not a 64-hex SHA-256', path: file };
+  }
+  if (!FLEET_CONFIG_POLICIES.includes(policy)) {
+    return { ok: false, code: 'FLEET_CONFIG_BAD_POLICY', error: 'policy must be config, home or account', path: file };
+  }
+
+  const previous = readFleetConfig(file);
+  if (previous.ok !== true) return previous;
+
+  const now = Number.isInteger(input?.now) ? input.now : Date.now();
+  const backup = previous.config === null
+    ? null
+    : `${file}.bak-${new Date(now).toISOString().replace(/[:.]/g, '-')}`;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    if (backup !== null) {
+      copyFileSync(file, backup);
+      try { chmodSync(backup, 0o600); } catch { /* Windows ACL carries it */ }
+    }
+    const tmp = `${file}.tmp-${process.pid}-${now}`;
+    writeFileSync(tmp, `${JSON.stringify({
+      version: FLEET_CONFIG_VERSION,
+      fleet_key: fleetKey,
+      fleet_key_policy: policy,
+      fleet_id: fleetId,
+      updated_at: new Date(now).toISOString(),
+    }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try { chmodSync(tmp, 0o600); } catch { /* Windows ACL carries it */ }
+    const check = readFleetConfig(tmp);
+    if (check.ok !== true || check.config === null || check.config.fleetKey !== fleetKey || check.config.fleetId !== fleetId) {
+      rmSync(tmp, { force: true });
+      throw new Error(check.ok === true ? 'the written pin did not validate' : check.error);
+    }
+    try {
+      renameSync(tmp, file);
+    } catch (error) {
+      rmSync(tmp, { force: true });
+      throw error;
+    }
+    return { ok: true, path: file, backup };
+  } catch (error) {
+    // Roll back to the previous file. Without a backup, remove a partial new file rather than leave
+    // a half-written pin for the next boot.
+    try {
+      if (backup !== null && existsSync(backup)) copyFileSync(backup, file);
+      else rmSync(file, { force: true });
+    } catch { /* best effort: the original error is more useful */ }
+    return {
+      ok: false,
+      code: 'FLEET_CONFIG_WRITE_FAILED',
+      error: error instanceof Error ? error.message : String(error),
+      path: file,
+    };
+  }
+}

package/src/plugin/fleet-home.mjs

@@ -0,0 +1,263 @@
+/**
+ * Per-account fleet homes: the local answer to "which fleet was this machine in last time it was
+ * signed in to this account?"
+ *
+ * # Why a file, and why this file
+ *
+ * The account-derived key is deterministic, but it is not a complete history. A fleet can have
+ * been created with an explicit key, or before account-derived keys existed, and the derived key
+ * then points at a different (new) fleet. Replacing the old key on every account switch is what
+ * made one machine's sign-in move the whole fleet -- v2.2.0's `fleetKeyPolicy: account`.
+ *
+ * The home map is deliberately **per account**: switching from A to B does not erase A's home, so
+ * switching back to A returns to A's fleet instead of minting another one. It is written beside
+ * `device.json` (same directory, same permissions concerns) and contains encoded fleet keys, which
+ * are credentials: the file is 0600 where the platform honours it.
+ *
+ * # Failure policy
+ *
+ * `readFleetHome` never silently treats a corrupt file as "no homes". A machine in `home` policy
+ * that cannot read its history must stay unbound and report the fault rather than derive a new key
+ * and create a new fleet -- that automatic migration is the behaviour this module exists to stop.
+ * The caller decides whether to block (home policy) or continue without the history (account
+ * policy).
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** The file beside `device.json`; the basename is part of the operator-visible contract. */
+export const FLEET_HOME_FILE = 'fleet-home.json';
+
+/** Bump only with a reader that still understands the previous shape. */
+export const FLEET_HOME_VERSION = 1;
+
+const ACCOUNT_CODE_RE = /^[0-9a-f]{8}$/;
+const MAX_KEY_LENGTH = 4096;
+const MAX_ACCOUNTS = 64;
+
+/**
+ * @param {string|null} deviceFile Absolute path of `device.json`, or null when unknown.
+ * @returns {string|null} The path of the home file, or null when there is no state directory.
+ */
+export function fleetHomePath(deviceFile) {
+  return typeof deviceFile === 'string' && deviceFile !== '' ? join(dirname(deviceFile), FLEET_HOME_FILE) : null;
+}
+
+/**
+ * Read the map. Missing file means "no history yet", which is a success, not an error.
+ *
+ * @param {string|null} file
+ * @returns {{ok: true, homes: Record<string, {fleet_key: string, updated_at: string}>, lastAccount: string|null, path: string|null}
+ *   | {ok: false, code: string, error: string, path: string|null}}
+ */
+export function readFleetHome(file) {
+  if (file === null || file === undefined || file === '') return { ok: true, homes: {}, lastAccount: null, path: null };
+  if (!existsSync(file)) return { ok: true, homes: {}, lastAccount: null, path: file };
+
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (error) {
+    return {
+      ok: false,
+      code: 'FLEET_HOME_UNREADABLE',
+      error: error instanceof Error ? error.message : String(error),
+      path: file,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return {
+      ok: false,
+      code: 'FLEET_HOME_CORRUPT',
+      error: `not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      path: file,
+    };
+  }
+  if (parsed === null || typeof parsed !== 'object'
+    || parsed.version !== FLEET_HOME_VERSION
+    || parsed.homes === null || typeof parsed.homes !== 'object' || Array.isArray(parsed.homes)) {
+    return {
+      ok: false,
+      code: 'FLEET_HOME_CORRUPT',
+      error: `expected {version: ${FLEET_HOME_VERSION}, homes: {…}}`,
+      path: file,
+    };
+  }
+
+  const homes = {};
+  for (const [accountCode, entry] of Object.entries(parsed.homes)) {
+    if (!ACCOUNT_CODE_RE.test(accountCode)) {
+      return { ok: false, code: 'FLEET_HOME_CORRUPT', error: `bad account code ${accountCode}`, path: file };
+    }
+    if (entry === null || typeof entry !== 'object'
+      || typeof entry.fleet_key !== 'string' || entry.fleet_key === ''
+      || entry.fleet_key.length > MAX_KEY_LENGTH) {
+      return { ok: false, code: 'FLEET_HOME_CORRUPT', error: `bad home for ${accountCode}`, path: file };
+    }
+    homes[accountCode] = {
+      fleet_key: entry.fleet_key,
+      updated_at: typeof entry.updated_at === 'string' ? entry.updated_at : '',
+    };
+  }
+  if (Object.keys(homes).length > MAX_ACCOUNTS) {
+    return { ok: false, code: 'FLEET_HOME_CORRUPT', error: `more than ${MAX_ACCOUNTS} account homes`, path: file };
+  }
+  const lastAccount = typeof parsed.last_account === 'string' && ACCOUNT_CODE_RE.test(parsed.last_account)
+    ? parsed.last_account
+    : null;
+  return { ok: true, homes, lastAccount, path: file };
+}
+
+/**
+ * @param {Record<string, {fleet_key: string}>} homes
+ * @param {string|null} accountCode
+ * @returns {{fleet_key: string, updated_at: string}|null}
+ */
+export function getFleetHome(homes, accountCode) {
+  if (typeof accountCode !== 'string' || !ACCOUNT_CODE_RE.test(accountCode)) return null;
+  const entry = homes?.[accountCode];
+  return entry !== undefined && typeof entry.fleet_key === 'string' && entry.fleet_key !== '' ? entry : null;
+}
+
+/**
+ * Should a machine with an existing token and no recorded home stay exactly where it is?
+ *
+ * This is the migration guard for 2.2.0 -> 2.2.1. Such a machine may be sitting in an old fleet
+ * whose key no longer exists in its profile; deriving the account key at that moment is precisely
+ * how an upgrade would move it (and, if the account is shared, tempt everyone else to follow).
+ * Staying put and reporting "no home key" is recoverable; silently re-pairing is not.
+ *
+ * A configured key is excluded: it is the operator's explicit seed and is used instead of the
+ * account key. A fresh, unpaired machine is excluded too: it has no fleet to preserve.
+ *
+ * @param {{policy?: string, hasHome?: boolean, hasConfiguredKey?: boolean, hasToken?: boolean,
+ *   accountChanged?: boolean}} input
+ * @returns {boolean}
+ */
+export function shouldPreserveExistingFleet({
+  policy = 'home',
+  hasHome = false,
+  hasConfiguredKey = false,
+  hasToken = false,
+  accountChanged = false,
+} = {}) {
+  return policy === 'home'
+    && hasHome !== true
+    && hasConfiguredKey !== true
+    && hasToken === true
+    && accountChanged !== true;
+}
+
+/**
+ * Write the complete state atomically. Internal: callers have already validated what they add.
+ *
+ * @param {string} file
+ * @param {{homes: Record<string, {fleet_key: string, updated_at: string}>, lastAccount: string|null}} state
+ * @returns {{ok: true, path: string}|{ok: false, code: string, error: string, path: string|null}}
+ */
+function writeFleetState(file, state) {
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(tmp, `${JSON.stringify({
+      version: FLEET_HOME_VERSION,
+      last_account: state.lastAccount,
+      homes: state.homes,
+    }, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    try { chmodSync(tmp, 0o600); } catch { /* Windows: the file ACL carries the protection */ }
+    try {
+      renameSync(tmp, file);
+    } catch {
+      // Windows can refuse to replace a file that another handle has open. The old file is gone
+      // only after the copy exists, so this fallback cannot turn a failed write into no file.
+      rmSync(file, { force: true });
+      renameSync(tmp, file);
+    }
+    return { ok: true, path: file };
+  } catch (error) {
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    return {
+      ok: false,
+      code: 'FLEET_HOME_WRITE_FAILED',
+      error: error instanceof Error ? error.message : String(error),
+      path: file,
+    };
+  }
+}
+
+/**
+ * Remember one account's fleet key. Other accounts are preserved verbatim, and the last account
+ * that successfully bound is recorded so a restart can tell "same account, no home yet" apart from
+ * "the account actually changed".
+ *
+ * The write is temp-file + rename in the same directory, so a crash leaves either the old complete
+ * map or the new complete map. A corrupt existing map is **not** overwritten: silently replacing a
+ * history we cannot parse is how the recovery data would be lost exactly when it is needed.
+ *
+ * @param {string|null} file
+ * @param {{accountCode: string, fleetKey: string, lastAccount?: string|null, now?: number}} input
+ * @returns {{ok: true, path: string}|{ok: false, code: string, error: string, path: string|null}}
+ */
+export function rememberFleetHome(file, input) {
+  if (file === null || file === undefined || file === '') {
+    return { ok: false, code: 'FLEET_HOME_NO_PATH', error: 'no state directory is known', path: null };
+  }
+  const accountCode = typeof input?.accountCode === 'string' ? input.accountCode : '';
+  if (!ACCOUNT_CODE_RE.test(accountCode)) {
+    return { ok: false, code: 'FLEET_HOME_BAD_ACCOUNT', error: 'account code is not 8 hex characters', path: file };
+  }
+  const fleetKey = typeof input?.fleetKey === 'string' ? input.fleetKey : '';
+  if (fleetKey === '' || fleetKey.length > MAX_KEY_LENGTH) {
+    return { ok: false, code: 'FLEET_HOME_BAD_KEY', error: 'fleet key is empty or too long', path: file };
+  }
+  const previous = readFleetHome(file);
+  if (previous.ok !== true) return previous;
+  const homes = {
+    ...previous.homes,
+    [accountCode]: {
+      fleet_key: fleetKey,
+      updated_at: new Date(Number.isInteger(input?.now) ? input.now : Date.now()).toISOString(),
+    },
+  };
+  if (Object.keys(homes).length > MAX_ACCOUNTS) {
+    return { ok: false, code: 'FLEET_HOME_TOO_MANY', error: `more than ${MAX_ACCOUNTS} account homes`, path: file };
+  }
+  const lastAccount = typeof input?.lastAccount === 'string' && ACCOUNT_CODE_RE.test(input.lastAccount)
+    ? input.lastAccount
+    : accountCode;
+  if (previous.homes[accountCode]?.fleet_key === fleetKey && previous.lastAccount === lastAccount) {
+    return { ok: true, path: file };
+  }
+  return writeFleetState(file, { homes, lastAccount });
+}
+
+/**
+ * Record which account this machine last bound under, without changing any fleet key.
+ *
+ * Used by the migration guard: a paired machine that cannot derive a key still has an account
+ * identity, and persisting it is what lets the *next* real account switch be recognised.
+ *
+ * @param {string|null} file
+ * @param {string} accountCode
+ * @returns {{ok: true, path: string}|{ok: false, code: string, error: string, path: string|null}}
+ */
+export function rememberFleetAccount(file, accountCode) {
+  if (file === null || file === undefined || file === '') {
+    return { ok: false, code: 'FLEET_HOME_NO_PATH', error: 'no state directory is known', path: null };
+  }
+  if (!ACCOUNT_CODE_RE.test(typeof accountCode === 'string' ? accountCode : '')) {
+    return { ok: false, code: 'FLEET_HOME_BAD_ACCOUNT', error: 'account code is not 8 hex characters', path: file };
+  }
+  const previous = readFleetHome(file);
+  if (previous.ok !== true) return previous;
+  if (previous.lastAccount === accountCode) return { ok: true, path: file };
+  return writeFleetState(file, { homes: previous.homes, lastAccount: accountCode });
+}