@timurproko/a1 0.2.7-dev.1241 → 0.2.7-dev.1245

package/dist/foundation/supervision/server.js

@@ -5,7 +5,7 @@ import { platform } from "node:os";
 import { dirname } from "node:path";
 import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
-import { processIsAlive } from "../release/index.js";
+import { listRecordedEndpoints, readEndpointMetadata, supervisorProcessState, currentSupervisorStartIdentity, withEndpointLock, processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveProductPaths } from "./paths.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
@@ -43,7 +43,7 @@ export async function commitEndpointMetadata(path, source, operations = {}) {
 export class SupervisorServer {
     id = randomUUID();
     bootNonce;
-    pidStartIdentity = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
+    pidStartIdentity = currentSupervisorStartIdentity();
     startedAt = new Date().toISOString();
     paths;
     #server = null;
@@ -84,7 +84,7 @@ export class SupervisorServer {
         this.supersededPollMs = supersededPollMs;
         this.bootNonce = bootNonce;
         this.paths = paths;
-        for (const instance of store.loadActiveLaunchInstances())
+        for (const instance of store.loadActiveLaunchInstances(bootNonce))
             this.#instances.set(instance.id, instance);
     }
     snapshot() {
@@ -98,41 +98,60 @@ export class SupervisorServer {
         };
     }
     async listen() {
-        if (this.#server)
-            throw new Error("supervisor is already listening");
-        await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
-        await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
-        if (platform() !== "win32") {
-            if (this.paths.endpointDirectory)
-                await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
-            const existing = await lstat(this.paths.endpoint).catch(error => {
-                if (error.code === "ENOENT")
-                    return null;
-                throw error;
-            });
-            if (existing) {
-                if (await endpointIsLive(this.paths.endpoint)) {
-                    throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`)), { code: "EADDRINUSE" });
+        await withEndpointLock(this.paths.endpointMetadataPath, async () => {
+            if (this.#server)
+                throw new Error("supervisor is already listening");
+            await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
+            await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
+            const recorded = await readEndpointMetadata(this.paths.endpointMetadataPath);
+            if (recorded && await supervisorProcessState(recorded) !== "gone") {
+                throw Object.assign(new Error("another supervisor still owns this endpoint"), { code: "EADDRINUSE" });
+            }
+            if (platform() !== "win32") {
+                if (this.paths.endpointDirectory)
+                    await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
+                const existing = await lstat(this.paths.endpoint).catch(error => {
+                    if (error.code === "ENOENT")
+                        return null;
+                    throw error;
+                });
+                if (existing) {
+                    if (await endpointIsLive(this.paths.endpoint)) {
+                        throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`)), { code: "EADDRINUSE" });
+                    }
+                    await rm(this.paths.endpoint, { force: true });
                 }
-                await rm(this.paths.endpoint, { force: true });
             }
-        }
-        const server = createServer(socket => this.#attach(socket));
-        this.#server = server;
-        await new Promise((resolve, reject) => {
-            server.once("error", reject);
-            server.listen(this.paths.endpoint, () => {
-                this.#ownsEndpoint = true;
-                server.off("error", reject);
-                resolve();
+            const server = createServer(socket => this.#attach(socket));
+            this.#server = server;
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(this.paths.endpoint, () => {
+                    this.#ownsEndpoint = true;
+                    server.off("error", reject);
+                    resolve();
+                });
+            });
+            // Concurrency: only the bound winner may reconcile shared control data. Other cohort boots
+            // remain protected even when temporarily unresponsive; their instances never become ours.
+            await withEndpointLock(this.paths.databasePath, async () => {
+                // Concurrency: all cohorts sharing SQLite serialize boot reconciliation plus publication, so a new
+                // cohort cannot insert instances between another cohort's inventory and stale-row update.
+                const protectedBoots = [];
+                for (const other of await listRecordedEndpoints(this.paths)) {
+                    if (other.paths.endpointMetadataPath !== this.paths.endpointMetadataPath
+                        && await supervisorProcessState(other.metadata) !== "gone")
+                        protectedBoots.push(other.metadata.bootNonce);
+                }
+                this.store.reconcilePriorBootLaunchInstances(this.bootNonce, new Date().toISOString(), protectedBoots);
+                await this.#writeEndpointMetadata();
             });
+            if (this.readActiveReleaseId) {
+                const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
+                poll.unref();
+                this.#supersededPoll = poll;
+            }
         });
-        await this.#writeEndpointMetadata();
-        if (this.readActiveReleaseId) {
-            const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
-            poll.unref();
-            this.#supersededPoll = poll;
-        }
     }
     // Invariant: superseding a cohort never interrupts its held instances; it retires only when empty.
     async #refreshCohortRole() {
@@ -167,27 +186,29 @@ export class SupervisorServer {
         this.#supersededPoll = null;
         for (const client of this.#clients)
             client.destroy();
-        try {
-            await this.#metadataWrites.catch(() => undefined);
-            if (this.#ownsEndpoint) {
-                // Concurrency: remove only our publication, before releasing the listening endpoint.
-                // A contender that failed to bind must never erase the successful owner's discovery file.
-                const metadata = await readFile(this.paths.endpointMetadataPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
-                if (metadata?.supervisorId === this.id && metadata.bootNonce === this.bootNonce) {
-                    await rm(this.paths.endpointMetadataPath, { force: true });
+        await withEndpointLock(this.paths.endpointMetadataPath, async () => {
+            try {
+                await this.#metadataWrites.catch(() => undefined);
+                if (this.#ownsEndpoint) {
+                    // Concurrency: remove only our publication, before releasing the listening endpoint.
+                    // A contender that failed to bind must never erase the successful owner's discovery file.
+                    const metadata = await readFile(this.paths.endpointMetadataPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
+                    if (metadata?.supervisorId === this.id && metadata.bootNonce === this.bootNonce) {
+                        await rm(this.paths.endpointMetadataPath, { force: true });
+                    }
+                    // Platform: Node unlinks its Unix socket when the server closes; unlinking it early would
+                    // let a replacement bind before the old server finishes releasing that path.
                 }
-                // Platform: Node unlinks its Unix socket when the server closes; unlinking it early would
-                // let a replacement bind before the old server finishes releasing that path.
             }
-        }
-        finally {
-            // Platform: a metadata sharing error must not leave a bound but undiscoverable listener.
-            if (this.#server)
-                await new Promise(resolve => this.#server?.close(() => resolve()));
-            this.#server = null;
-            this.#ownsEndpoint = false;
-            this.store.close();
-        }
+            finally {
+                // Platform: a metadata sharing error must not leave a bound but undiscoverable listener.
+                if (this.#server)
+                    await new Promise(resolve => this.#server?.close(() => resolve()));
+                this.#server = null;
+                this.#ownsEndpoint = false;
+                this.store.close();
+            }
+        });
     }
     async closeForReleaseReplacement(stopAgents) {
         await this.close(stopAgents);
@@ -518,6 +539,7 @@ export class SupervisorServer {
             supervisorId: this.id,
             pid: process.pid,
             pidStartIdentity: this.pidStartIdentity,
+            nativeStartIdentity: this.pidStartIdentity,
             bootNonce: this.bootNonce,
             endpoint: this.paths.endpoint,
             databasePath: this.paths.databasePath,

package/dist/integrations/pi/components/shell-footer-status.js

@@ -7,7 +7,7 @@ import { KeybindingsManager } from "./upstream/adjacent/core/keybindings.js";
 import { StatusIndicator, WorkingStatusIndicator } from "./upstream/components/status-indicator.js";
 import { protectPiPromptChipPresentation } from "./prompt-chip-presentation.js";
 import { PINNED_PI_LAYOUT, piTheme, } from "./theme.js";
-import { createTuiFacade, ensureTheme, renderPiShellBlockedUpdateStatus, renderPiShellInstalledUpdateStatus, piShellVisibleWidth, } from "./shell-shared-facade.js";
+import { createTuiFacade, ensureTheme, renderPiShellInstalledUpdateStatus, piShellVisibleWidth, } from "./shell-shared-facade.js";
 export function createPiShellHeader(options = {}) {
     ensureTheme();
     let expanded = options.expanded ?? false;
@@ -233,9 +233,7 @@ function appendInstalledUpdateStatus(rows, width, view, progressPresentation) {
         return rows;
     const status = view.diagnostics.some(diagnostic => diagnostic.code === "release-update-installed")
         ? renderPiShellInstalledUpdateStatus(width)
-        : view.diagnostics.some(diagnostic => diagnostic.code === "release-update-blocked")
-            ? renderPiShellBlockedUpdateStatus(width)
-            : "";
+        : "";
     if (status.length === 0)
         return rows;
     const statusWidth = piShellVisibleWidth(status);

package/dist/integrations/pi/components/shell-shared-facade.d.ts

@@ -9,11 +9,8 @@ import { KeybindingsManager } from "./upstream/adjacent/core/keybindings.js";
 export declare const piShellVisibleWidth: typeof visibleWidth;
 export declare const piShellTruncateToWidth: (text: string, width: number) => string;
 export declare const INSTALLED_UPDATE_STATUS_TEXT = "Update installed, restart to update";
-export declare const BLOCKED_UPDATE_STATUS_TEXT = "Update prepared; activation blocked";
 /** Shared green restart notice for the pinned status and bare-A1 prompt overlay. */
 export declare function renderPiShellInstalledUpdateStatus(width: number): string;
-/** Sanitized warning for a certified candidate that cannot yet preserve resident continuity. */
-export declare function renderPiShellBlockedUpdateStatus(width: number): string;
 /** A clickable URL in pinned Pi's grammar: an OSC 8 link where the terminal supports one, the plain URL otherwise. */
 export declare const piShellHyperlink: (url: string, text?: string) => string;
 export interface PiShellComponentPort extends PresentationComponentPort {

package/dist/integrations/pi/components/shell-shared-facade.js

@@ -5,7 +5,6 @@ import { ensurePiTheme, piTheme, } from "./theme.js";
 export const piShellVisibleWidth = visibleWidth;
 export const piShellTruncateToWidth = (text, width) => truncateToWidth(text, width, "");
 export const INSTALLED_UPDATE_STATUS_TEXT = "Update installed, restart to update";
-export const BLOCKED_UPDATE_STATUS_TEXT = "Update prepared; activation blocked";
 /** Shared green restart notice for the pinned status and bare-A1 prompt overlay. */
 export function renderPiShellInstalledUpdateStatus(width) {
     if (width <= 0)
@@ -13,13 +12,6 @@ export function renderPiShellInstalledUpdateStatus(width) {
     ensurePiTheme();
     return piShellTruncateToWidth(piTheme().fg("success", INSTALLED_UPDATE_STATUS_TEXT), width);
 }
-/** Sanitized warning for a certified candidate that cannot yet preserve resident continuity. */
-export function renderPiShellBlockedUpdateStatus(width) {
-    if (width <= 0)
-        return "";
-    ensurePiTheme();
-    return piShellTruncateToWidth(piTheme().fg("warning", BLOCKED_UPDATE_STATUS_TEXT), width);
-}
 /** A clickable URL in pinned Pi's grammar: an OSC 8 link where the terminal supports one, the plain URL otherwise. */
 export const piShellHyperlink = (url, text = url) => hyperlink(url, text);
 // Provenance: pinned from packages/coding-agent/src/core/slash-commands.ts at 914cf14.

package/dist/native/darwin-arm64/manifest.json

@@ -7,11 +7,11 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-11-05T06:57:12.752Z",
+  "builtAt": "2026-11-06T08:23:55.616Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "a87eaaffcd986b624c8b044b756446cc1bdaf4334a1775b97820542fe34f9fb7",
-    "size": 456080
+    "sha256": "9ab579426034c752ef8ed53a789566f5b7cfe102149d30c28f4bdb60e73107c5",
+    "size": 456272
   },
   "provenance": {
     "language": "Rust",

package/dist/native/darwin-arm64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "arm64",
   "target": "aarch64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-11-05T07:01:22.443Z",
+  "builtAt": "2026-11-06T08:27:51.656Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "084c00e2cf786f3a8c92deb5f3c7939b87f8f09e481559001acc96dc38c87349",
-    "size": 6625792
+    "sha256": "b2548f95b9660b11b6d28fb4b35f254cde9940d9d19233517bb70507ffcf76ab",
+    "size": 6626528
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/native/darwin-x64/manifest.json

@@ -7,11 +7,11 @@
   "platform": "darwin",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-11-05T06:57:19.328Z",
+  "builtAt": "2026-11-06T08:24:02.357Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "783a65f0de287a1c02cd5429dbe97bc8633f4cc8a7b92e3e961180b9bdcff814",
-    "size": 444248
+    "sha256": "65f3a469a6faa9b578bc095e7559012775ee85e5b93cbc9451c62604f769146e",
+    "size": 452648
   },
   "provenance": {
     "language": "Rust",

package/dist/native/darwin-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-apple-darwin",
   "capability": "supported",
-  "builtAt": "2026-11-05T07:04:03.142Z",
+  "builtAt": "2026-11-06T08:31:58.733Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "34a1dc77e44453dd8c60d170577615e228bc091c70c1bd86401be2bc849b105f",
-    "size": 7213944
+    "sha256": "cd1103472889d53e2e039cf7673b2fe6e9e0937234591b1202234d0c1c357d2a",
+    "size": 7226904
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/native/linux-x64/manifest.json

@@ -7,11 +7,11 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-11-05T06:57:04.789Z",
+  "builtAt": "2026-11-06T08:23:51.242Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "118e5954e3864672bd8482ab7edf419cb27dcdf2533720316979b7f5cc5a53a5",
-    "size": 491520
+    "sha256": "64232d4c827bb7f69c14612986f9b6780a0593d8842cd039a411b6bfe29cd5da",
+    "size": 500264
   },
   "provenance": {
     "language": "Rust",

package/dist/native/linux-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-unknown-linux-gnu",
   "capability": "supported",
-  "builtAt": "2026-11-05T07:00:29.693Z",
+  "builtAt": "2026-11-06T08:26:29.024Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "272d4279ceda5baabd5edac6f71b8ede554c0420f5fc7f205c4b4a3072fc4851",
-    "size": 7997704
+    "sha256": "f5abfe9464780c9acdf85dfbf8a0f194bf0355188ab23feaa09cb7df84363088",
+    "size": 8010960
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/native/win32-x64/manifest.json

@@ -7,11 +7,11 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-11-05T06:57:43.401Z",
+  "builtAt": "2026-11-06T08:24:41.351Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "2414e9a2269c6cb9f0ce275f0ea7b8147b5078be54c4bbc5c53dadb41ddad9f4",
-    "size": 402432
+    "sha256": "dab6b6aed5ab24435d7814fc5099f26707486ee187551ff1dfd939679682f32b",
+    "size": 414208
   },
   "provenance": {
     "language": "Rust",

package/dist/native/win32-x64/terminal-host.manifest.json

@@ -9,11 +9,11 @@
   "architecture": "x64",
   "target": "x86_64-pc-windows-msvc",
   "capability": "supported",
-  "builtAt": "2026-11-05T06:59:52.560Z",
+  "builtAt": "2026-11-06T08:29:00.280Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "919ab8121819cd7bc886d64cb8e4f7a422c7263e2aba0afa51319baef9a05adc",
-    "size": 7115264
+    "sha256": "00dc90f70d76ff36418a301d36dd406d143a6bf1da6b56e24ae5341b4e0c7d8e",
+    "size": 7131136
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/docs/architecture/project-structure.md

@@ -47,6 +47,8 @@ Three layer boundaries hold regardless of the DAG: `src/contracts/*` import noth
 
 `src/cli` contains command policy but delegates runtime work. `src/composition` is the concrete dependency-injection boundary: it may know both neutral contracts and Pi implementations, while product features receive vendor-neutral ports. Foundation modules never import product features. Pi package knowledge remains inside the Pi adapter owners.
 
+Release-owned endpoint observation and recovery coordinate with supervision-owned publication and storage-owned boot reconciliation through the process guardian's OS-released gates; see [startup recovery](../launch-recovery.md) for the identity, concurrency, and diagnostic boundaries.
+
 Shared code moves to foundation only when it is product-agnostic, has a precise contract, and has more than one real consumer. Do not create `core`, `common`, `utils`, or `misc` dumping grounds.
 
 ## Feature ownership
@@ -113,6 +115,8 @@ Passing an absolute `path` to `EnterWorktree` is reserved for a worktree created
 
 Inventory is read-only and advisory because another runtime may win a later race. A successful link response confirming the exact canonical worktree is required before planning, implementation, test, or delivery-documentation edits. If inventory or linking fails, reports a live/unverifiable owner, loses a race, or confirms another path, stop task edits and report the blocker; use a separate fresh worktree rather than overriding, unlinking, or recovering that owner. A session resuming an existing delivery or switching streams atomically claims and links the exact worktree before editing it.
 
+Mutation-gate corruption and transient startup-registration failures have a separate [worktree-link recovery procedure](../worktree-link-recovery.md). Automatic recovery never overrides a live or unverifiable editing claim; ambiguous legacy gates remain protected.
+
 The link acquires a cooperative live-session editing claim and switches bare A1's footer repository context and pull-request discovery. It does not change process or tool cwd, create a Git worktree lock, or register, release, or authorize cleanup. Clean unlink/disposal releases live editing authority; a crashed owner becomes reusable only after exact process death is verified. Repository commands therefore keep an explicit worktree path. The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, adopt, move, or remove another session's worktree.
 
 An agent that directly chooses a transient file path for a PR/comment body, command payload, captured output, temporary patch/diff, or ad hoc log must place it beneath the linked worktree's exact `.artifacts/` root, never the primary checkout, another worktree, OS temp, home/desktop, or a sibling path. Such scratch remains ignored, unstaged, uncommitted, disposable, non-authoritative, and secret-free. This repository path rule does not relocate storage internally selected by tools, product runtime code, or hermetic tests.

package/docs/launch-recovery.md

@@ -0,0 +1,23 @@
+# Startup recovery after process termination
+
+A1 reconciles recoverable runtime ownership automatically when the user starts it again after a process crash or forced termination. Users should not need to find PIDs, delete session or control databases, restart a supervisor, or reboot to clear a stale record.
+
+## Recovery boundary
+
+Supervisor metadata carries an additive native process-creation token. Endpoint handshakes still use the existing supervisor, boot, release, and opaque start-identity fields for compatibility; new supervisors use their native token in that start field as well. A failed probe is retried; native process inspection distinguishes a terminated process object or reused PID from the recorded owner. Older records remain readable: an absent process is reclaimable, while a live legacy PID is not treated as dead merely because its timestamp format differs. Windows and macOS native creation times strictly later than a legacy publication, with a one-second margin, can disprove that recorded ownership. Tick-only Linux legacy evidence remains conservative until absence or a matching handshake establishes the outcome.
+
+Endpoint retirement requires the same publication and a fresh dead-owner observation under a native file-descriptor gate. The gate is never deleted; the OS releases its lock on exit, including forced exit. Supervisor binding, Unix stale-socket removal, metadata publication, and closure use that gate. Losing startups cannot delete the winner's endpoint. A separate shared-database gate serializes boot reconciliation and publication across cohorts. Only the bound winner reconciles old rows, and recorded surviving cohort boots remain protected.
+
+Successful recovery is silent and continues the original profile, launch mode, and session selection. Saved sessions are not deleted or rewritten by endpoint recovery. Resident holders and their session-writer locks retain their independent ownership; restarting a supervisor is not permission to stop a resident tab or create a second session writer.
+
+## Exceptional failures
+
+An uninspectable or genuinely unresponsive live owner is preserved after bounded retries. Empty saved instance lists are not authority to terminate it. The command returns a short recovery message instead of an uncaught stack or the old internal uncertain-live-ownership paragraph. Missing native recovery support or inaccessible runtime storage remains an installation or permission failure, not proof that an owner is dead.
+
+A recovery attempt may replace one bounded `<endpoint-metadata>.recovery.json` summary containing only a reason, attempt count, and timestamp. It is diagnostic only, contains no session data or credentials, and never grants cleanup authority. The `.authority` gate files are also not user cleanup targets.
+
+This restores launch availability, not killed process memory. Killing every Node process also kills the terminal-restoration watcher; no alternative executable is started to evade that limitation. Real OS permission failures, damaged installations, and persistently live unresponsive services cannot be converted into safe success by ignoring ownership.
+
+## Regression boundaries
+
+The focused fixtures use isolated runtime/data roots and recorded fixture process identities. They cover supervisor, guardian, root-runtime, recovery-gate, PID-reuse, concurrent-startup, and Windows all-recorded-Node loss, plus native resident server/holder/tab loss in the resident lane. They never terminate processes by image name. Another managed runtime, a separate cohort, saved session bytes, and an unrelated sentinel process establish the preservation boundaries.

package/docs/worktree-link-recovery.md

@@ -0,0 +1,37 @@
+# Worktree-link recovery
+
+A1 coordinates worktree-claim mutations separately from the editing claims themselves. Recovering a mutation gate never grants permission to take another live agent's worktree or to delete worktree contents.
+
+## Automatic recovery
+
+Updated A1 holds an OS lock on the persistent `session-worktree-claims/mutation.authority` file. The OS releases it when the process exits, including a crash. `mutation.lock` is now a persistent directory that blocks older file-lock writers; its `owner.json` is only diagnostic metadata.
+
+The next mutation safely recovers abandoned owner/pending metadata after taking native authority. Empty, truncated, NUL-filled, or otherwise malformed metadata does not prevent this recovery. One bounded `recovery.json` records the recovery reason/time, not the original bytes or session contents. A live native holder remains protected. Acquisition waits at most two seconds by default and honors cancellation.
+
+If startup registration fails temporarily, the running session retries on its 30-second refresh interval. Slow attempts are coalesced rather than queued indefinitely. Once registration succeeds, retry the explicit worktree link in the same session. Switching an agent's session replaces its publication identity, and disposal drains publication before releasing claims.
+
+Inventory remains read-only. It can conservatively show unverifiable status until a mutation has recovered abandoned state; inventory does not perform repair.
+
+## Older lock files and mixed versions
+
+An existing regular-file `mutation.lock` belongs to the old protocol. Updated A1 cannot safely prove that no old writer/reclaimer is using it, even if a PID in the file is dead. It therefore retains the file and reports `worktree-legacy-recovery-required` rather than guessing or endlessly reporting generic busy.
+
+For this one-time legacy case, stop all older A1 processes normally, move only that exact regular lock file to a backup while they are stopped, then start updated A1. Keep sessions, runtime records, associations, editing claims, Git locks, and worktrees. Reinstalling/downgrading alone does not clear persisted legacy state. Never move the new directory or delete `mutation.authority` while A1 is running.
+
+When the old gate is absent, updated A1 initializes its compatibility barrier automatically. Older versions cannot mutate worktree claims after this point: all participating sessions must use the updated version. This intentionally prevents two incompatible mutation protocols from running concurrently. The installed native addon must support the new gate; there is no unsafe PID-file fallback if the addon is missing or outdated.
+
+## Diagnostics
+
+| Code | Meaning / next step |
+| --- | --- |
+| `worktree-claim-busy` | A mutation still holds native authority. Retry the link shortly; runtime registration retries automatically. |
+| `worktree-legacy-recovery-required` | Retained old-format gate. Use the stopped-process legacy procedure above. |
+| `worktree-coordination-unavailable` | Missing or outdated native support. Repair/update the A1 installation. |
+| `worktree-coordination-io` | Gate/metadata filesystem access failed. Check permissions and storage availability. |
+| `worktree-coordination-boundary` | Unexpected file type, link, or entry. Retain it for inspection; do not clear the store. |
+| `session-runtime-unavailable` | Runtime registration has not succeeded. Retry after the next refresh and address any specific coordination failure. |
+| `process-inspection-unavailable` / `session-runtime-unverifiable` | Exact process identity cannot be checked. Repair inspection support; no ownership takeover is authorized. |
+| `worktree-active-in-another-session` | Another live agent owns the target. Use a different worktree or have that owner release it. |
+| `worktree-owner-unverifiable` | The editing claim itself is uncertain. Gate recovery cannot make that claim available. |
+
+Diagnostics do not expose another session's process identity, session file, transcript, or credentials. The mechanism does not repair arbitrary damaged claim records, change tool cwd, or grant Git/cleanup authority.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.1241",
+  "version": "0.2.7-dev.1245",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -11,6 +11,9 @@
     "resident-control-v1",
     "resident-workspace-v1"
   ],
+  "updateCommandContracts": [
+    "update-release-v1"
+  ],
   "packageManager": "npm@11.13.0",
   "bin": {
     "a1": "bin/cli.js"
@@ -123,7 +126,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "c3b7a3fd5d44c998b87847f0f79422bdbb459355",
-    "pullRequest": 865
+    "source": "fc4a2588e22b6d90034465d80d7923c8fede91d8",
+    "pullRequest": 870
   }
 }