@timurproko/a1 0.2.7-dev.1244 → 0.2.7-dev.1249

package/dist/foundation/storage/control-store.js

@@ -30,7 +30,7 @@ const LAUNCH_INSTANCES_TABLE = `
 export class ControlStore {
     database;
     bootNonce;
-    constructor(path, bootNonce = null) {
+    constructor(path, bootNonce = null, options = {}) {
         this.bootNonce = bootNonce;
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         this.database = new DatabaseSync(path);
@@ -38,7 +38,7 @@ export class ControlStore {
             this.database.exec("PRAGMA journal_mode = WAL");
             this.database.exec("PRAGMA foreign_keys = ON");
             this.migrate();
-            if (bootNonce !== null)
+            if (bootNonce !== null && options.reconcileOnOpen !== false)
                 this.reconcilePriorBootLaunchInstances(bootNonce);
         }
         catch (error) {
@@ -284,16 +284,16 @@ export class ControlStore {
             .run(terminalState, completedAt, JSON.stringify(outcome), instanceId, ownerClientId, this.bootNonce);
         return Number(result.changes) === 1;
     }
-    loadActiveLaunchInstances() {
+    loadActiveLaunchInstances(bootNonce) {
         return this.database.prepare(`SELECT * FROM launch_instances
-      WHERE state IN ('requested', 'active', 'stopping') ORDER BY created_at, id`).all()
+      WHERE state IN ('requested', 'active', 'stopping') ${bootNonce === undefined ? "" : "AND owner_boot_nonce = ?"} ORDER BY created_at, id`).all(...(bootNonce === undefined ? [] : [bootNonce]))
             .map(launchInstanceFromRow);
     }
     loadLaunchInstance(instanceId) {
         const row = this.database.prepare("SELECT * FROM launch_instances WHERE id = ?").get(instanceId);
         return row ? launchInstanceFromRow(row) : null;
     }
-    reconcilePriorBootLaunchInstances(bootNonce, reconciledAt = new Date().toISOString()) {
+    reconcilePriorBootLaunchInstances(bootNonce, reconciledAt = new Date().toISOString(), protectedBoots = []) {
         const outcome = {
             kind: "interrupted",
             reason: "supervisor-disconnect",
@@ -301,8 +301,9 @@ export class ControlStore {
         };
         const result = this.database.prepare(`UPDATE launch_instances
       SET state = 'interrupted', completed_at = ?, outcome_json = ?
-      WHERE state IN ('requested', 'active', 'stopping') AND owner_boot_nonce <> ?`)
-            .run(reconciledAt, JSON.stringify(outcome), bootNonce);
+      WHERE state IN ('requested', 'active', 'stopping') AND owner_boot_nonce <> ?
+      ${protectedBoots.length === 0 ? "" : `AND owner_boot_nonce NOT IN (${protectedBoots.map(() => "?").join(",")})`}`)
+            .run(reconciledAt, JSON.stringify(outcome), bootNonce, ...protectedBoots);
         return Number(result.changes);
     }
     close() {

package/dist/foundation/supervision/main.js

@@ -36,7 +36,9 @@ export async function runSupervisor(arguments_ = []) {
         paths = { ...productPaths, ...resolveCohortEndpoint(productPaths, release.releaseId) };
         stage = "storage";
         const bootNonce = randomUUID();
-        const store = new ControlStore(paths.databasePath, bootNonce);
+        // Concurrency: opening SQLite does not establish endpoint authority. The winning listener
+        // reconciles old boots only after binding; losing startup attempts must not mutate live rows.
+        const store = new ControlStore(paths.databasePath, bootNonce, { reconcileOnOpen: false });
         const cohortState = new CohortStateStore(paths.dataDir);
         server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => {
             const transaction = await new UpdateTransactionStore(paths.dataDir).read();

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,32 @@ 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 });
+        // Concurrency: disconnect reconciliation can still commit a terminal outcome after its
+        // bounded process wait. Settle it before retiring the endpoint and closing shared storage.
+        await Promise.allSettled(this.#reconciliations.values());
+        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);
@@ -434,6 +458,8 @@ export class SupervisorServer {
         const existing = this.#reconciliations.get(instanceId);
         if (existing)
             return existing;
+        if (this.#closing)
+            return Promise.resolve();
         const reconciliation = this.#performReconciliation(instanceId).finally(() => this.#reconciliations.delete(instanceId));
         this.#reconciliations.set(instanceId, reconciliation);
         return reconciliation;
@@ -518,6 +544,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/engine/compaction-progress.js

@@ -19,7 +19,7 @@ export function observeCompactionProgress(session, onProgress) {
     let expected = DEFAULT_EXPECTED_COMPACTION_SUMMARY_CHARS;
     let reported = null;
     const report = (percent = Math.min(MAX_STREAMING_PERCENT, Math.floor((100 * streamed) / expected))) => {
-        if (percent === reported)
+        if (reported !== null && percent <= reported)
             return;
         reported = percent;
         onProgress(percent);
@@ -29,6 +29,18 @@ export function observeCompactionProgress(session, onProgress) {
         if (!active || disposed)
             return stream;
         const observed = generation;
+        // Concurrency: Pi resolves result() before an independent iterator receives the terminal
+        // event, so register first to publish 100 before Pi can emit compaction_end.
+        try {
+            void stream.result().then(result => {
+                if (observed !== generation || !active || disposed || result.stopReason !== "stop")
+                    return;
+                report(COMPLETE_PERCENT);
+            }, () => undefined);
+        }
+        catch {
+            // Invariant: optional observation never affects the stream returned to Pi.
+        }
         void (async () => {
             report();
             // Invariant: observation never affects the request; a stream that cannot be iterated ends observation only.
@@ -41,10 +53,6 @@ export function observeCompactionProgress(session, onProgress) {
                         report();
                     }
                 }
-                // Invariant: normal exhaustion is the only observed completion boundary. The real
-                // compaction_end event owns work-state exit; errors and stale generations never claim 100%.
-                if (observed === generation && active && !disposed)
-                    report(COMPLETE_PERCENT);
             }
             catch {
                 return;

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

@@ -7,11 +7,11 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-11-06T06:57:04.765Z",
+  "builtAt": "2026-11-06T18:31:39.019Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "5a314f46b164ef006957528ea7b1743e104895449a1b5a9e3c8b5adbf7122d33",
-    "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-06T07:00:26.658Z",
+  "builtAt": "2026-11-06T18:34:18.531Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "b2548f95b9660b11b6d28fb4b35f254cde9940d9d19233517bb70507ffcf76ab",
-    "size": 6626528
+    "sha256": "7dcfd045769d22ffd59f11974a7d5d490199ee67eec288e92224be4c049857d7",
+    "size": 6645216
   },
   "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-06T06:57:12.911Z",
+  "builtAt": "2026-11-06T18:31:46.232Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "b4d66ed5920c3b2d4ac1cb658fe87549cdad2f81948dbe8cfa698ff6d87162e1",
-    "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-06T07:03:27.415Z",
+  "builtAt": "2026-11-06T18:37:01.604Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "cd1103472889d53e2e039cf7673b2fe6e9e0937234591b1202234d0c1c357d2a",
-    "size": 7226904
+    "sha256": "691f821e9a4d2da71866dbe09742909d8f8c46fc330bdb917e8b81de2fa83450",
+    "size": 7249568
   },
   "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-06T06:56:45.470Z",
+  "builtAt": "2026-11-06T18:26:24.402Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "18442075f91a02d22071548c0a2c882c69ee04b2e48e0b1130f23a86c5b258ca",
-    "size": 491536
+    "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-06T06:59:02.808Z",
+  "builtAt": "2026-11-06T18:28:48.745Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "f5abfe9464780c9acdf85dfbf8a0f194bf0355188ab23feaa09cb7df84363088",
-    "size": 8010960
+    "sha256": "70f658de12b148666d0414e8a0fd0d8a10844d7a0ee6e2b11c2013477f4db91f",
+    "size": 8033296
   },
   "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-06T06:57:32.942Z",
+  "builtAt": "2026-11-06T18:27:06.362Z",
   "artifact": {
     "filename": "process-guardian.node",
-    "sha256": "eb4519e51e5c77a740b9c290e28def2293363675b103a21388532fa73d208893",
-    "size": 402432
+    "sha256": "e8f4a87276da9375c998d9cdb28c2ed5d4ed857089001c338a689bb045d75dad",
+    "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-06T06:59:37.419Z",
+  "builtAt": "2026-11-06T18:29:48.572Z",
   "artifact": {
     "filename": "terminal-host.node",
-    "sha256": "148523e2ee5648749b4c5b84518e3d120aacf247cdf8620c3fa205df5c960dff",
-    "size": 7131136
+    "sha256": "712c6ed93b1d9fa307a6e12045222c1cbf34be1044360d1a0070d694bdfe2f55",
+    "size": 7155712
   },
   "entry": {
     "filename": "dist/foundation/resident-tabs/host-entry.js",

package/dist/ui/settings/declarations.d.ts

@@ -230,7 +230,7 @@ export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
     }>;
     readonly tabBarRightItems: Readonly<{
         id: "tabBarRightItems";
-        label: "Right side";
+        label: "Widgets";
         section: Readonly<{
             id: "tabs";
             title: "Tab Bar";

package/dist/ui/settings/declarations.js

@@ -177,7 +177,7 @@ export const OWNED_SETTING_DECLARATIONS = Object.freeze({
     }),
     tabBarRightItems: Object.freeze({
         id: "tabBarRightItems",
-        label: "Right side",
+        label: "Widgets",
         section: TABS_SECTION,
         description: "Choose whether the tab bar's right side shows the executing Version, Time, both, or neither.",
         application: "live",

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
@@ -93,31 +95,37 @@ Build output mirrors the production namespaces directly under ignored `dist/`, w
 
 Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
 
-From the initial working directory, run `a1 session worktrees` to inspect cooperative live ownership before selecting an existing checkout. A `busy` or `unverifiable` worktree is unavailable. An `available` checkout may be reused only when its exact branch, OpenSpec change, and pull request match the requested stream and atomic `a1 session link-worktree <absolute-worktree>` succeeds; names, similar files, recency, cleanliness, and ancestry are not ownership evidence. Otherwise create a fresh task branch/worktree, link it from the owning A1 session, and continue to address it explicitly:
+### Common Git workflow
 
-```sh
-a1 session worktrees
-git fetch origin develop
-git worktree add -b <type>/<short-description> .worktrees/<task-id> origin/develop
-a1 session link-worktree <absolute-worktree>
-git -C .worktrees/<task-id> status
-```
+External agents use ordinary Git without an A1 installation, runtime, or session link. Keep primary on `develop`, run the bounded cleanup sweep and relay its `lines`, then inspect `git worktree list --porcelain` from primary. Inventory is read-only and advisory; it is not atomic editing exclusion or permission to adopt a checkout.
 
-Claude Code sessions have no A1 shell-tool session, so they link with Claude Code's `EnterWorktree` tool by task name. The tracked `.claude/settings.json` wires a `WorktreeCreate` hook, `scripts/governance/claude-worktree-create.mjs`, that creates `.worktrees/<task-id>` detached at fresh `origin/develop`, or returns it when it is already registered, so Claude Code anchors the session there without an approval prompt. The agent then creates the task branch inside it:
+For a new delivery, create a unique absent task path and a new topic branch from freshly fetched `origin/develop`, unless the maintainer selected another base. For example, with primary at `D:/Git/a1` and unused task/branch names:
 
-```sh
-git -C .worktrees/<task-id> switch -c <type>/<short-description>
+```bash
+cd /d/Git/a1 && git fetch origin develop && git worktree add -b feature/example-task .worktrees/example-task origin/develop && git -C .worktrees/example-task rev-parse --show-toplevel --git-common-dir && git -C .worktrees/example-task status --short --branch
 ```
 
-Passing an absolute `path` to `EnterWorktree` is reserved for a worktree created by hand, from the primary checkout, before any shell command in that session; Claude Code otherwise keeps its shell tools anchored to the primary checkout and refuses their commands. The matching `WorktreeRemove` hook declines removal, so sessions leave with `ExitWorktree` `keep` and worktrees are removed only by the cleanup tool.
+Successful creation by this session establishes provenance for that fresh checkout. Before planning, implementation, test, or delivery-documentation edits, verify the exact canonical root, common Git repository, intended branch, and working-tree state. Relative Git directory results must resolve to the primary repository's common directory. A path/branch collision never permits force creation, overwriting, or adoption of the existing checkout. A context mismatch means stop edits and report the blocker; never fall back to task edits in primary.
+
+### Resume and ownership
+
+Reuse an existing checkout only when its exact branch, OpenSpec change, and PR match the requested stream and continuing ownership or explicit handoff from the prior owner or maintainer is established without conflicting ownership evidence. Names, similar files, recency, cleanliness, and ancestry are not ownership evidence. Inspect Git worktree locks and the cleanup journal's `status`; claim any released cleanup registration through the [cleanup ownership protocol](../local-worktree-cleanup.md#resume-or-recover-ownership) before editing. An owned registration requires matching owner authority. Neither an unregistered path nor a successful cleanup claim proves that no other editor is using it.
+
+Known live editing claims, foreign cleanup ownership, Git locks, and unverifiable handoffs block reuse. Stop edits and report the blocker, or use a safe fresh worktree without overriding, recovering, unlocking, unlinking, or waiting out another owner. Preserve the existing delivery's branch/history/PR: do not force a branch checked out elsewhere or create a replacement PR to evade ownership. If the same stream cannot safely continue, report that concrete blocker.
+
+Repeat exact-context and ownership verification when resuming or switching streams. Handoffs name the absolute worktree, branch, change, PR, and whether editing ownership is being handed over. This is cooperative coordination, not enforcement against arbitrary external editors. Missing A1 integration alone never blocks external agents and is not evidence of a conflicting owner.
+
+### Environment-specific adapters
+
+Inside an active A1 shell-tool session only, run `a1 session worktrees` and `a1 session link-worktree <absolute-worktree>` before edits to acquire the runtime's editing claim and footer association. An `available` result still needs atomic linking; a `busy` or `unverifiable` owner, failed association, lost race, or different returned path blocks edits there. A failed stream switch preserves the prior association. External agents use the common Git workflow instead of fabricating runtime identities or starting A1 just to satisfy repository policy.
 
-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.
+A stale Git registration elsewhere whose directory is missing and whose row is `prunable` may be pruned before retrying inventory; this does not permit removing a live checkout. Mutation-gate corruption and transient A1 startup-registration failures have a separate [worktree-link recovery procedure](../worktree-link-recovery.md). Recovery never overrides a live or unverifiable editing claim.
 
-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.
+Claude Code uses its established `EnterWorktree` tool by task name. The tracked `.claude/settings.json` wires `scripts/governance/claude-worktree-create.mjs` to create `.worktrees/<task-id>` detached at fresh `origin/develop`, or return an already registered path. The agent must still establish ownership before reusing that path and create the topic branch in a new detached worktree before editing. Passing an absolute `path` to `EnterWorktree` is reserved for a worktree created by hand, from primary before any shell command in that session. The matching `WorktreeRemove` hook declines removal: leave with `ExitWorktree` `keep` and use only the guarded cleanup tool for removal. Other agents do not need these tools or hooks.
 
-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.
+A1 linking acquires a cooperative live-session editing claim and switches footer repository/PR discovery; an existing draft PR is not required when linking first succeeds. Clean unlink/disposal releases that runtime claim; a crashed A1 owner becomes reusable only after exact process death is verified. Runtime association does not change process or tool cwd, create a Git lock, or register, release, or authorize cleanup. Context verification and editing handoff also grant no acceptance, finalization, merge, deletion, or cleanup authority. 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.
+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 verified task 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.
 
 ## Documentation and comments
 

package/docs/architecture/toolchain.md

@@ -40,7 +40,7 @@ Source builds require Rust/Cargo 1.85 or newer; `rust-toolchain.toml` pins the e
 
 `npm run build` compiles `native/process-guardian` as the host platform's Node-API 9 addon, places `process-guardian.node` under `dist/native/<platform>-<architecture>/`, loads it to observe its version identity, and writes the v2 integrity manifest. It also builds the current platform's release-profile `terminal-host.node`, whose v2 manifest binds the addon, `dist/foundation/resident-tabs/host-entry.js`, and notices, so the ordinary `npm run build && ./scripts/dev` handoff exercises resident tabs without deployment. On Windows the normal build reuses a compatible ignored terminal-library cache or downloads the newest compatible library from the current branch or a successful CI run belonging to a pull request already merged into `develop`, then links it under the crate's manifest verification; it never silently invokes the quarantined Zig package fetch. An unavailable or mismatched prerequisite fails the build instead of leaving a nominally successful single-agent-only tree. The npm `prepare` lifecycle and validation preflight use the explicit core build because selected native lanes assemble and certify terminal hosts separately.
 
-Preview and stable candidate workflows build the addons on isolated Windows, Linux, and macOS arm64 runners, cross-compile the macOS x64 addons on the arm64 runner with `--target x86_64-apple-darwin`, and assemble all targets before packing. Those release runners retain their explicit `npm run build:terminal-host` step and pinned Zig input rather than consuming a workstation cache. Cross-compiled artifacts record a Mach-O architecture check when they cannot be loaded on the producing runner. Supported native code is always loaded by Node; an absent, incompatible, or unsupported addon fails before runtime startup rather than falling back to PID-only cleanup. The process-guardian addon inherits terminal handles but transports no terminal bytes. Its separate Node-hosted exit watcher restores terminal state after guardian failure, subject to the documented node-wide-kill gap. See [`process-guardian-provenance.md`](process-guardian-provenance.md), [`terminal-host-provenance.md`](terminal-host-provenance.md), and [`resident-tabs.md`](resident-tabs.md).
+Preview and stable candidate workflows build the addons on isolated Windows, Linux, and macOS arm64 runners, cross-compile the macOS x64 addons on the arm64 runner with `--target x86_64-apple-darwin`, and assemble all targets before packing. Those release runners retain their explicit `npm run build:terminal-host` step and pinned Zig input rather than consuming a workstation cache; Development validation lanes may instead restore a CI-built release addon from an exact-input cache and re-verify it (see [`../ci-release-runbook.md`](../ci-release-runbook.md)). Cross-compiled artifacts record a Mach-O architecture check when they cannot be loaded on the producing runner. Supported native code is always loaded by Node; an absent, incompatible, or unsupported addon fails before runtime startup rather than falling back to PID-only cleanup. The process-guardian addon inherits terminal handles but transports no terminal bytes. Its separate Node-hosted exit watcher restores terminal state after guardian failure, subject to the documented node-wide-kill gap. See [`process-guardian-provenance.md`](process-guardian-provenance.md), [`terminal-host-provenance.md`](terminal-host-provenance.md), and [`resident-tabs.md`](resident-tabs.md).
 
 ## Gates
 

package/docs/ci-release-runbook.md

@@ -103,6 +103,8 @@ The real three-release `update-predecessor` scenario is exhaustive because its f
 
 Development outcomes report each owner/scope invocation separately while sharing authenticated build/package preparation. The aggregate reports setup, scope, job, aggregate-processing, total runner, and runner-critical-path durations. The acceptance targets are at most eight minutes of runner critical path and five minutes for one PR-required scope; an over-target result remains unmet without retries, timeout increases, workload reduction, or mutable installation caches. Hosted queue time is reported separately when available and is not counted as test execution.
 
+Candidate-packing Development lanes restore the release `terminal-host.node`, its manifest, and its third-party notices from an exact-input `actions/cache` entry keyed by the native tree, `rust-toolchain.toml`, the provenance configuration, the build scripts, the pinned Zig version, and the runner image. On a hit the lane skips the Rust toolchain, Zig, and `cargo` build steps, re-records the manifest's `host-entry.js` digest from the current TypeScript build (`build-terminal-host.mjs --reuse`), and still runs `verify-native-artifacts.mjs --local` before the build receipt; any tampered or mismatched restored file fails the lane instead of rebuilding. A miss builds as before and saves the result. This is build-output reuse with a complete input key, not a mutable installation cache, and publication lanes keep building in-run. Before this reuse, each `packs_candidate` lane spent 2.6 to 3.4 minutes on the release build, and a resident-tabs pull request repeated it in four lanes. Likewise the Linux terminal-host lane caches the `cargo-fuzz 0.13.2` binary by version and nightly date instead of compiling it each run, and the three terminal-host partition jobs run only their `role_integration` slice, so the crate's unit tests execute once per target per run rather than four times.
+
 Inspect local committed and worktree impact without running tests:
 
 ```sh

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/local-worktree-cleanup.md

@@ -184,6 +184,10 @@ After a low-level release, request a pass from the stable checkout if queue clea
 
 ## Resume or recover ownership
 
+This protocol works for external agents without an A1 installation, runtime, or session link. First verify the exact delivery branch, change, and PR plus continuing editing ownership or explicit handoff under the [worktree protocol](architecture/project-structure.md#development-worktrees). Inspect Git locks and this tool's `status` from the primary checkout. A familiar path, clean status, or missing A1 runtime is not evidence of another editor's absence. Known live editing claims, foreign cleanup ownership, Git locks, and unverifiable handoffs block reuse.
+
+For a worktree with no cleanup registration, this tool supplies no ownership claim: a fresh checkout created by this session or verified continuing ownership/explicit handoff establishes editing provenance. Do not register with fabricated PR identities or create a cleanup claim solely to simulate an A1 link. For a released registration, the atomic claim below is mandatory before editing; an already-owned registration requires matching owner authority. A failed claim never authorizes recovery or takeover. A successful cleanup claim prevents cleanup but does not prove exclusive editing ownership, and an A1 runtime link does not claim the cleanup journal. Both remain cooperative, independent safeguards.
+
 Before resuming a released worktree, acquire it:
 
 ```bash