@timurproko/a1 0.2.7-dev.1287 → 0.2.7-dev.1288

package/dist/cli/dispatch.js

@@ -23,6 +23,7 @@ export function cliUsage(capabilities) {
         "worktree enter <branch> [--base <branch>]",
         "worktree attach <path>",
         "worktree detach",
+        "worktree complete [--change <id>] [--pr <number>]",
         "worktree list",
         "session worktrees",
         "session link-worktree <path>",
@@ -59,6 +60,7 @@ export function cliHelp(capabilities) {
         `  ${command} worktree enter <branch> [--base <branch>]`,
         `  ${command} worktree attach <path>`,
         `  ${command} worktree detach`,
+        `  ${command} worktree complete [--change <id>] [--pr <number>]`,
         `  ${command} worktree list`,
         "",
         "Session context (compatibility aliases):",
@@ -155,7 +157,24 @@ function parseWorktree(rest) {
     if ((action === "detach" || action === "list") && value === undefined) {
         return { kind: "session-context", request: { action: action === "detach" ? "unlink-worktree" : "worktrees" } };
     }
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic("worktree accepts enter <branch> [--base <branch>], attach <path>, detach, or list.") };
+    if (action === "complete") {
+        const selectors = rest.slice(1);
+        let change, pr;
+        let valid = selectors.length % 2 === 0;
+        for (let index = 0; valid && index < selectors.length; index += 2) {
+            const name = selectors[index], selected = selectors[index + 1] ?? "";
+            if (name === "--change" && change === undefined && /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(selected))
+                change = selected;
+            else if (name === "--pr" && pr === undefined && /^[1-9][0-9]{0,8}$/u.test(selected))
+                pr = Number(selected);
+            else
+                valid = false;
+        }
+        if (valid) {
+            return { kind: "session-context", request: { action: "complete-worktree", ...(change === undefined ? {} : { change }), ...(pr === undefined ? {} : { pr }) } };
+        }
+    }
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic("worktree accepts enter <branch> [--base <branch>], attach <path>, detach, complete [--change <id>] [--pr <number>], or list.") };
 }
 function parseSessionContext(rest) {
     const [action, value, extra] = rest;

package/dist/cli/session-context.js

@@ -15,6 +15,9 @@ export async function runSessionContextCommand(request, options = {}) {
         const outcome = await updateSessionRepositoryContext({ sessionId: identity.sessionId, sessionFile: identity.sessionFile }, request, { runtimeId: identity.runtimeId, inspectProcess: options.inspectProcess ?? inspectLiveProcess });
         if (outcome.kind === "unlinked")
             stdout("Session worktree context cleared.\n");
+        if (outcome.kind === "completing") {
+            stdout(`Session returned to ${outcome.startupRoot}; left ${outcome.cwd} (${outcome.branch}). Repository cleanup runs when this command's shell exits and is reported with its result.\n`);
+        }
         if (outcome.kind === "linked")
             stdout(`Session worktree context linked: ${outcome.cwd} (${outcome.branch})\n`);
         if (outcome.kind === "worktrees") {
@@ -57,6 +60,8 @@ function recoveryDetail(code) {
         "worktree-primary-checkout": "attach a task worktree, not the primary checkout; use worktree enter to create one",
         "worktree-git-locked": "Git has locked this worktree; retain it and ask its owner to release the lock",
         "worktree-foreign-repository": "the selected worktree belongs to a different repository; the previous attachment was preserved",
+        "worktree-not-attached": "no task worktree is attached to this session; nothing was changed",
+        "worktree-attachment-invalid": "the attached worktree is no longer a valid Git worktree; run worktree detach to return to the startup checkout",
         "worktree-context-changed": "the attachment changed during the operation; no ownership was overridden",
     };
     return code === null ? undefined : details[code];

package/dist/composition/session-runtime-registry.d.ts

@@ -17,7 +17,9 @@ export declare class SessionRuntimeRegistry {
         revision: string;
     } | null>;
     /** Strict tool cwd lookup: transient startup failure never redirects a write to primary. */
-    toolReaderFor(agentId: string | undefined): (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>;
+    toolReaderFor(agentId: string | undefined): ((sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>) & {
+        settleShell: (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string | null>;
+    };
     /** Drain publication before releasing claims; never republish after disposal. */
     dispose(): Promise<void>;
 }

package/dist/composition/session-runtime-registry.js

@@ -3,6 +3,8 @@ export class SessionRuntimeRegistry {
     #options;
     #identities = new Map();
     #activated = new Map();
+    // Invariant: a released invalid attachment is reported by the agent's next tool call instead of running elsewhere.
+    #released = new Map();
     #abort = new AbortController();
     #owner = null;
     #timer = null;
@@ -26,7 +28,7 @@ export class SessionRuntimeRegistry {
                 const owner = await this.#ownerIdentity();
                 if (owner === null || !this.#current(agentId, identity))
                     return null;
-                const { activateSessionRepositoryContext, readActiveSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
+                const { activateSessionRepositoryContext, readActiveSessionRepositoryContext, releaseInvalidSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
                 if (!this.#current(agentId, identity))
                     return null;
                 const options = {
@@ -51,6 +53,14 @@ export class SessionRuntimeRegistry {
                 }
                 catch (error) {
                     const code = error instanceof Error && "code" in error ? error.code : null;
+                    if (code === "worktree-attachment-invalid") {
+                        const released = await releaseInvalidSessionRepositoryContext(identity, options);
+                        if (released !== null && this.#current(agentId, identity)) {
+                            this.#released.set(agentId, { identity, message: `attached worktree ${released.worktreeRoot} is no longer a valid Git worktree; `
+                                    + `this session was detached and now uses ${released.startupRoot}. Nothing was deleted and this call did not run; retry it from that directory.` });
+                            return null;
+                        }
+                    }
                     if ((code === "session-runtime-unavailable" || code === "worktree-context-changed") && this.#current(agentId, identity)) {
                         this.#activated.delete(agentId);
                     }
@@ -62,7 +72,18 @@ export class SessionRuntimeRegistry {
     /** Strict tool cwd lookup: transient startup failure never redirects a write to primary. */
     toolReaderFor(agentId) {
         const read = this.readerFor(agentId);
-        return async (sessionId, sessionFile, signal) => {
+        /** Run a completion the just-finished shell requested, from this stable process rather than that shell. */
+        const settleShell = async (sessionId, sessionFile, signal) => {
+            const { runtimeId, inspectProcess } = this.#options;
+            if (this.#disposed || runtimeId === undefined || inspectProcess === undefined)
+                return null;
+            const { describeWorktreeCompletion, settleSessionWorktreeCompletion } = await import("../foundation/lifecycle/session-worktree-completion.js");
+            const result = await settleSessionWorktreeCompletion({ sessionId, sessionFile }, {
+                runtimeId, inspectProcess, signal, ...(agentId === undefined ? {} : { agentId }),
+            });
+            return result === null ? null : describeWorktreeCompletion(result);
+        };
+        return Object.assign(async (sessionId, sessionFile, signal) => {
             const { retrySessionCoordination } = await import("../foundation/lifecycle/session-context-retry.js");
             return await retrySessionCoordination(async () => {
                 signal.throwIfAborted();
@@ -75,12 +96,20 @@ export class SessionRuntimeRegistry {
                 if (active?.sessionId !== sessionId || active.sessionFile !== sessionFile) {
                     throw Object.assign(new Error("worktree runtime registration is still recovering"), { code: "session-runtime-unavailable" });
                 }
+                const released = this.#released.get(agentId);
+                if (released !== undefined) {
+                    this.#released.delete(agentId);
+                    // Invariant: work addressed to the lost checkout fails once; it is never silently applied to the startup checkout.
+                    if (released.identity.sessionId === sessionId && released.identity.sessionFile === sessionFile) {
+                        throw Object.assign(new Error(released.message), { code: "worktree-attachment-invalid" });
+                    }
+                }
                 if (context !== null)
                     return context.cwd;
                 const { readSessionStartupRoot } = await import("../foundation/lifecycle/session-repository-context.js");
                 return await readSessionStartupRoot({ sessionId, sessionFile });
             }, 8_000, signal);
-        };
+        }, { settleShell });
     }
     /** Drain publication before releasing claims; never republish after disposal. */
     async dispose() {

package/dist/features/launch/session-context.d.ts

@@ -9,6 +9,10 @@ export type SessionContextRequest = {
     readonly base?: string;
 } | {
     readonly action: "unlink-worktree";
+} | {
+    readonly action: "complete-worktree";
+    readonly change?: string;
+    readonly pr?: number;
 } | {
     readonly action: "worktrees";
 };
@@ -18,6 +22,11 @@ export type SessionContextOutcome = {
     readonly branch: string;
 } | {
     readonly kind: "unlinked";
+} | {
+    readonly kind: "completing";
+    readonly cwd: string;
+    readonly branch: string;
+    readonly startupRoot: string;
 } | {
     readonly kind: "worktrees";
     readonly entries: readonly SessionWorktreeInventoryEntry[];

package/dist/features/launch/session-context.js

@@ -1,4 +1,4 @@
-import { clearSessionRepositoryContext, enterSessionRepositoryWorktree, listSessionRepositoryWorktrees, retrySessionCoordination, setSessionRepositoryContext, } from "../../foundation/lifecycle/index.js";
+import { clearSessionRepositoryContext, enterSessionRepositoryWorktree, listSessionRepositoryWorktrees, requestSessionWorktreeCompletion, retrySessionCoordination, setSessionRepositoryContext, } from "../../foundation/lifecycle/index.js";
 export { PRIMARY_SESSION_AGENT_ID } from "../../foundation/lifecycle/index.js";
 export async function updateSessionRepositoryContext(identity, request, runtime) {
     const options = {
@@ -14,6 +14,12 @@ export async function updateSessionRepositoryContext(identity, request, runtime)
             await clearSessionRepositoryContext(identity, options);
             return { kind: "unlinked" };
         }
+        if (request.action === "complete-worktree") {
+            return { kind: "completing", ...await requestSessionWorktreeCompletion(identity, {
+                    ...(request.change === undefined ? {} : { change: request.change }),
+                    ...(request.pr === undefined ? {} : { pr: request.pr }),
+                }, options) };
+        }
         if (request.action === "worktrees") {
             return { kind: "worktrees", entries: await listSessionRepositoryWorktrees(identity, options) };
         }

package/dist/foundation/lifecycle/index.d.ts

@@ -5,7 +5,9 @@ export { resolveProductPaths } from "./paths.js";
 export type { ProductPaths } from "./paths.js";
 export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
 export type { SessionSelection } from "./session-selection.js";
-export { PRIMARY_SESSION_AGENT_ID, activateSessionRepositoryContext, clearSessionRepositoryContext, listSessionRepositoryWorktrees, readActiveSessionRepositoryContext, readSessionStartupRoot, readSessionRepositoryContext, registerSessionRepositoryRuntime, releaseSessionRepositoryRuntime, setSessionRepositoryContext, withSessionRepositoryObservation, } from "./session-repository-context.js";
+export { PRIMARY_SESSION_AGENT_ID, activateSessionRepositoryContext, clearSessionRepositoryContext, listSessionRepositoryWorktrees, readActiveSessionRepositoryContext, readSessionStartupRoot, readSessionRepositoryContext, registerSessionRepositoryRuntime, releaseInvalidSessionRepositoryContext, releaseSessionRepositoryRuntime, setSessionRepositoryContext, withSessionRepositoryObservation, } from "./session-repository-context.js";
 export { retrySessionCoordination } from "./session-context-retry.js";
 export { enterSessionRepositoryWorktree } from "./session-worktree-entry.js";
-export type { SessionRepositoryContext, SessionRepositoryContextOptions, SessionRepositoryIdentity, SessionRepositoryObservation, SessionWorktreeInventoryEntry, SessionWorktreeStatus, } from "./session-repository-context.js";
+export { describeWorktreeCompletion, requestSessionWorktreeCompletion, settleSessionWorktreeCompletion, } from "./session-worktree-completion.js";
+export type { WorktreeCompletionRequest, WorktreeCompletionResult, WorktreeCompletionSelectors, } from "./session-worktree-completion.js";
+export type { ReleasedSessionAttachment, SessionRepositoryContext, SessionRepositoryContextOptions, SessionRepositoryIdentity, SessionRepositoryObservation, SessionWorktreeInventoryEntry, SessionWorktreeStatus, } from "./session-repository-context.js";

package/dist/foundation/lifecycle/index.js

@@ -2,6 +2,7 @@ export { assertLaunchProfileId } from "./model.js";
 export { PID_LIVENESS_IDENTITY, inspectLiveProcess } from "./process-liveness.js";
 export { resolveProductPaths } from "./paths.js";
 export { parseSessionSelection, sessionSelectionArguments } from "./session-selection.js";
-export { PRIMARY_SESSION_AGENT_ID, activateSessionRepositoryContext, clearSessionRepositoryContext, listSessionRepositoryWorktrees, readActiveSessionRepositoryContext, readSessionStartupRoot, readSessionRepositoryContext, registerSessionRepositoryRuntime, releaseSessionRepositoryRuntime, setSessionRepositoryContext, withSessionRepositoryObservation, } from "./session-repository-context.js";
+export { PRIMARY_SESSION_AGENT_ID, activateSessionRepositoryContext, clearSessionRepositoryContext, listSessionRepositoryWorktrees, readActiveSessionRepositoryContext, readSessionStartupRoot, readSessionRepositoryContext, registerSessionRepositoryRuntime, releaseInvalidSessionRepositoryContext, releaseSessionRepositoryRuntime, setSessionRepositoryContext, withSessionRepositoryObservation, } from "./session-repository-context.js";
 export { retrySessionCoordination } from "./session-context-retry.js";
 export { enterSessionRepositoryWorktree } from "./session-worktree-entry.js";
+export { describeWorktreeCompletion, requestSessionWorktreeCompletion, settleSessionWorktreeCompletion, } from "./session-worktree-completion.js";

package/dist/foundation/lifecycle/session-repository-context.d.ts

@@ -57,3 +57,30 @@ export declare function readSessionStartupRoot(identity: SessionRepositoryIdenti
 export declare function readActiveSessionRepositoryContext(identity: SessionRepositoryIdentity, options: SessionRepositoryContextOptions): Promise<SessionRepositoryObservation | null>;
 /** List same-repository worktrees without acquiring, releasing, or repairing an editing claim. */
 export declare function listSessionRepositoryWorktrees(identity: SessionRepositoryIdentity, options?: SessionRepositoryContextOptions): Promise<readonly SessionWorktreeInventoryEntry[]>;
+/** The released checkout and the verified startup root the session continues from. */
+export interface ReleasedSessionAttachment {
+    readonly worktreeRoot: string;
+    readonly startupRoot: string;
+}
+/**
+ * Release this session's own association and claim when its checkout is definitively gone.
+ * Uncertain validation keeps the attachment; files, branches, and other owners' claims are never touched.
+ */
+export declare function releaseInvalidSessionRepositoryContext(identity: SessionRepositoryIdentity, options: SessionRepositoryContextOptions): Promise<ReleasedSessionAttachment | null>;
+/** The checkout a session left for completion, with the verified startup root it continues from. */
+export interface DetachedSessionWorktree {
+    readonly startupRoot: string;
+    readonly commonDir: string;
+    readonly worktreeRoot: string;
+    readonly worktreeGitDir: string;
+    readonly branch: string;
+}
+/**
+ * Release a valid attachment this session owns, after `record` durably notes what was left.
+ * A failed check or record keeps the attachment; nothing on disk is deleted.
+ */
+export declare function detachSessionRepositoryContextForCompletion(identity: SessionRepositoryIdentity, options: SessionRepositoryContextOptions, record: (detached: DetachedSessionWorktree) => Promise<void>): Promise<DetachedSessionWorktree>;
+/** Whether any live runtime holds the editing claim of one checkout; an unreadable claim is never treated as absent. */
+export declare function sessionWorktreeClaimState(commonDir: string, gitDir: string, options?: SessionRepositoryContextOptions): Promise<"absent" | "live" | "unverifiable">;
+/** Private per-agent store for a completion requested by a shell and settled by its runtime. */
+export declare function sessionWorktreeCompletionPath(identity: SessionRepositoryIdentity, options: SessionRepositoryContextOptions): string;

package/dist/foundation/lifecycle/session-repository-context.js

@@ -16,6 +16,8 @@ const GIT_TIMEOUT_MS = 5_000;
 /** Records without an agent id were written by a single-agent release and belong to its one agent. */
 export const PRIMARY_SESSION_AGENT_ID = "primary";
 const RECORD_FORMAT_VERSION = 2;
+const NOT_A_WORKTREE_ROOT = "associated path must be a Git worktree root";
+const INVALID_ATTACHMENT = "worktree-attachment-invalid";
 /** Publish the exact live runtime that may acquire a delivery worktree. */
 export async function registerSessionRepositoryRuntime(identity, runtimeId, runtimeIdentity, options = {}) {
     const header = await readSessionHeader(identity);
@@ -417,16 +419,113 @@ async function validateContextRecord(header, record, signal) {
     if (record.sessionId !== header.id || record.sessionFile !== header.file)
         throw new Error("associated session identity changed");
     const startup = await readGitWorktreeIdentity(header.cwd, false, signal);
-    const selected = await readGitWorktreeIdentity(record.worktreeRoot, true, signal);
-    if (!samePath(startup.root, record.startupRoot)
-        || !samePath(startup.commonDir, record.startupCommonDir)
-        || !samePath(selected.root, record.worktreeRoot)
-        || !samePath(selected.commonDir, record.worktreeCommonDir)
-        || !samePath(selected.gitDir, record.worktreeGitDir)
+    if (!samePath(startup.root, record.startupRoot) || !samePath(startup.commonDir, record.startupCommonDir)) {
+        throw new Error("associated worktree identity changed");
+    }
+    // Invariant: only a verified startup checkout makes the attached checkout's absence definitive.
+    const invalid = (detail) => Object.assign(contextError(`attached worktree ${record.worktreeRoot} ${detail}`, INVALID_ATTACHMENT), { worktreeRoot: record.worktreeRoot, startupRoot: startup.root });
+    const missing = (error) => { if (isMissingPathError(error))
+        return null; throw error; };
+    const root = await realpath(record.worktreeRoot).catch(missing);
+    if (root === null)
+        throw invalid("no longer exists");
+    if (await lstat(join(root, ".git")).catch(missing) === null)
+        throw invalid("no longer has its Git pointer");
+    let selected;
+    try {
+        selected = await readGitWorktreeIdentity(root, true, signal);
+    }
+    catch (error) {
+        if (error instanceof Error && (error.message === NOT_A_WORKTREE_ROOT
+            || ("stderr" in error && String(error.stderr).includes("not a git repository"))))
+            throw invalid("is no longer a Git worktree");
+        throw error;
+    }
+    if (!samePath(selected.commonDir, record.worktreeCommonDir) || !samePath(selected.gitDir, record.worktreeGitDir)
         || !samePath(startup.commonDir, selected.commonDir))
+        throw invalid("was replaced by a different Git worktree");
+    if (!samePath(selected.root, record.worktreeRoot))
         throw new Error("associated worktree identity changed");
     return selected;
 }
+/**
+ * Release this session's own association and claim when its checkout is definitively gone.
+ * Uncertain validation keeps the attachment; files, branches, and other owners' claims are never touched.
+ */
+export async function releaseInvalidSessionRepositoryContext(identity, options) {
+    const header = await readSessionHeader(identity);
+    const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
+    return await withClaimLock(options, async () => {
+        await requireLiveRuntime(header, owner, options);
+        const record = await readContextRecord(header, options);
+        if (record === null)
+            return null;
+        const failure = await validateContextRecord(header, record, options.signal).then(() => null, error => error);
+        if (!isInvalidAttachment(failure))
+            return null;
+        await rm(contextRecordPath(header, options), { force: true });
+        await releaseClaimsOwnedBy(owner, null, options);
+        return { worktreeRoot: failure.worktreeRoot, startupRoot: failure.startupRoot };
+    });
+}
+/**
+ * Release a valid attachment this session owns, after `record` durably notes what was left.
+ * A failed check or record keeps the attachment; nothing on disk is deleted.
+ */
+export async function detachSessionRepositoryContextForCompletion(identity, options, record) {
+    const header = await readSessionHeader(identity);
+    const owner = { runtimeId: requireRuntimeId(options), agentId: requireAgentId(options) };
+    return await withClaimLock(options, async () => {
+        await requireLiveRuntime(header, owner, options);
+        const stored = await readContextRecord(header, options);
+        if (stored === null)
+            throw contextError("no task worktree is attached", "worktree-not-attached");
+        const selected = await validateContextRecord(header, stored, options.signal);
+        const claim = await readClaim(selected, options);
+        if (claim === null || claim === undefined || !claimMatchesWorktree(claim, selected) || !ownedBy(claim, owner)) {
+            throw contextError("the session no longer owns its attached worktree", "worktree-owner-unverifiable");
+        }
+        if (await lstat(join(selected.gitDir, "locked")).then(() => true, error => { if (isMissingPathError(error))
+            return false; throw error; })) {
+            throw contextError("selected worktree is locked in Git", "worktree-git-locked");
+        }
+        const detached = {
+            startupRoot: stored.startupRoot, commonDir: selected.commonDir, worktreeRoot: selected.root,
+            worktreeGitDir: selected.gitDir, branch: requireBranch(selected),
+        };
+        await record(detached);
+        await rm(contextRecordPath(header, options), { force: true });
+        await releaseClaimsOwnedBy(owner, null, options);
+        return detached;
+    });
+}
+/** Whether any live runtime holds the editing claim of one checkout; an unreadable claim is never treated as absent. */
+export async function sessionWorktreeClaimState(commonDir, gitDir, options = {}) {
+    const path = claimRecordPath(commonDir, gitDir, options);
+    if (await lstat(path).then(() => false, error => { if (isMissingPathError(error))
+        return true; throw error; }))
+        return "absent";
+    const claim = await readClaimRecordAt(path);
+    if (claim === null)
+        return "unverifiable";
+    try {
+        const observed = await requireInspector(options)(claim.pid);
+        return observed !== null && observed.pid === claim.pid && observed.startIdentity === claim.startIdentity ? "live" : "absent";
+    }
+    catch {
+        return "unverifiable";
+    }
+}
+/** Private per-agent store for a completion requested by a shell and settled by its runtime. */
+export function sessionWorktreeCompletionPath(identity, options) {
+    const key = `${requireRuntimeId(options)}\0${requireAgentId(options)}\0${identity.sessionId}`;
+    return join(claimStoreRoot(options), "completions", `${digest(key)}.json`);
+}
+function isInvalidAttachment(error) {
+    return error instanceof Error && "code" in error && error.code === INVALID_ATTACHMENT
+        && "worktreeRoot" in error && typeof error.worktreeRoot === "string"
+        && "startupRoot" in error && typeof error.startupRoot === "string";
+}
 /** Release one agent's claims except the one it keeps; sibling agents of the runtime are untouched. */
 async function releaseClaimsOwnedBy(owner, keepGitDir, options) {
     await releaseClaimsWhere(claim => ownedBy(claim, owner) && (keepGitDir === null || !samePath(claim.worktreeGitDir, keepGitDir)), options);
@@ -492,7 +591,7 @@ async function readGitWorktreeIdentity(path, requireWorktreeRoot, signal) {
         throw new Error("associated worktree identity is incomplete");
     const root = await realpath(rootValue);
     if (requireWorktreeRoot && !samePath(root, cwd))
-        throw new Error("associated path must be a Git worktree root");
+        throw new Error(NOT_A_WORKTREE_ROOT);
     const commonDir = await realpath(commonValue);
     const gitDir = await realpath(gitValue);
     let branch = null;

package/dist/foundation/lifecycle/session-worktree-completion.d.ts

@@ -0,0 +1,35 @@
+import { type SessionRepositoryContextOptions, type SessionRepositoryIdentity } from "./session-repository-context.js";
+export interface WorktreeCompletionSelectors {
+    readonly change?: string;
+    readonly pr?: number;
+}
+export interface WorktreeCompletionRequest {
+    readonly startupRoot: string;
+    readonly cwd: string;
+    readonly branch: string;
+}
+/**
+ * `cleanup-finished` relays the repository command's own report, which stays authoritative:
+ * A1 never claims a removal it did not perform.
+ */
+export interface WorktreeCompletionResult extends WorktreeCompletionRequest {
+    readonly kind: "cleanup-finished" | "cleanup-failed" | "cleanup-unavailable" | "cleanup-skipped";
+    readonly detail: string;
+}
+export interface WorktreeCompletionSettleOptions extends SessionRepositoryContextOptions {
+    readonly now?: () => number;
+    /** Test seam for the repository cleanup command; production runs it without a shell. */
+    readonly run?: (command: string, arguments_: readonly string[], cwd: string, signal?: AbortSignal) => Promise<string>;
+}
+/**
+ * Leave the attached checkout so its cleanup can run after the issuing shell has exited.
+ * Unpublished content, a Git lock, or uncertain ownership keeps the session attached.
+ */
+export declare function requestSessionWorktreeCompletion(identity: SessionRepositoryIdentity, selectors: WorktreeCompletionSelectors, options: SessionRepositoryContextOptions): Promise<WorktreeCompletionRequest>;
+/**
+ * Run a pending completion's repository cleanup from the startup checkout. The request is consumed
+ * before anything runs, so it executes at most once; null means nothing was pending.
+ */
+export declare function settleSessionWorktreeCompletion(identity: SessionRepositoryIdentity, options: WorktreeCompletionSettleOptions): Promise<WorktreeCompletionResult | null>;
+/** The agent-facing account of a settled completion; the session is on the startup checkout in every case. */
+export declare function describeWorktreeCompletion(result: WorktreeCompletionResult): string;

package/dist/foundation/lifecycle/session-worktree-completion.js

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { detachSessionRepositoryContextForCompletion, readActiveSessionRepositoryContext, readSessionStartupRoot, sessionWorktreeClaimState, sessionWorktreeCompletionPath, } from "./session-repository-context.js";
+const SCHEMA = "a1-session-worktree-completion-v1";
+const CLEANUP_DECLARATION = ".a1/worktree.json";
+const MAX_RECORD_BYTES = 16 * 1024;
+const MAX_REPORT_CHARACTERS = 4_000;
+/** A request the runtime did not settle promptly is dropped, never run later by surprise. */
+const REQUEST_LIFETIME_MS = 5 * 60_000;
+const CLEANUP_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Leave the attached checkout so its cleanup can run after the issuing shell has exited.
+ * Unpublished content, a Git lock, or uncertain ownership keeps the session attached.
+ */
+export async function requestSessionWorktreeCompletion(identity, selectors, options) {
+    if (selectors.change !== undefined && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(selectors.change)) {
+        throw failure("worktree-completion-selector", "the change selector must be a kebab-case change id");
+    }
+    if (selectors.pr !== undefined && (!Number.isSafeInteger(selectors.pr) || selectors.pr < 1)) {
+        throw failure("worktree-completion-selector", "the pull-request selector must be a positive number");
+    }
+    const attached = await readActiveSessionRepositoryContext(identity, options);
+    if (attached === null)
+        throw failure("worktree-not-attached", "no task worktree is attached");
+    const status = await execute("git", ["-c", "core.hooksPath=/dev/null", "status", "--porcelain", "--untracked-files=all"], attached.cwd, options.signal);
+    const changed = status.split(/\r?\n/u).filter(Boolean);
+    if (changed.length > 0) {
+        const listed = changed.slice(0, 5).map(line => line.slice(3)).join(", ");
+        throw failure("worktree-content", `the attached worktree holds uncommitted or untracked content (${listed}${changed.length > 5 ? ", ..." : ""})`);
+    }
+    const path = sessionWorktreeCompletionPath(identity, options);
+    const detached = await detachSessionRepositoryContextForCompletion(identity, options, async (left) => {
+        if (!samePath(left.worktreeRoot, attached.cwd))
+            throw failure("worktree-context-changed", "the attachment changed during completion");
+        const record = {
+            schema: SCHEMA, sessionId: identity.sessionId, startupRoot: left.startupRoot, commonDir: left.commonDir,
+            worktreeRoot: left.worktreeRoot, worktreeGitDir: left.worktreeGitDir, branch: left.branch,
+            ...(selectors.change === undefined ? {} : { change: selectors.change }),
+            ...(selectors.pr === undefined ? {} : { pr: selectors.pr }),
+            requestedAt: Date.now(),
+        };
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => undefined);
+        }
+    });
+    return { startupRoot: detached.startupRoot, cwd: detached.worktreeRoot, branch: detached.branch };
+}
+/**
+ * Run a pending completion's repository cleanup from the startup checkout. The request is consumed
+ * before anything runs, so it executes at most once; null means nothing was pending.
+ */
+export async function settleSessionWorktreeCompletion(identity, options) {
+    const path = sessionWorktreeCompletionPath(identity, options);
+    const record = await readRecord(path);
+    await rm(path, { force: true });
+    if (record === null || record.sessionId !== identity.sessionId)
+        return null;
+    const request = { startupRoot: record.startupRoot, cwd: record.worktreeRoot, branch: record.branch };
+    const result = (kind, detail) => ({ ...request, kind, detail });
+    try {
+        if ((options.now ?? Date.now)() - record.requestedAt > REQUEST_LIFETIME_MS)
+            return result("cleanup-skipped", "the completion request expired before the runtime could settle it");
+        const startup = await realpath(await readSessionStartupRoot(identity));
+        if (!samePath(startup, record.startupRoot))
+            return result("cleanup-skipped", "the session's startup checkout is not the recorded primary checkout");
+        const claim = await sessionWorktreeClaimState(record.commonDir, record.worktreeGitDir, options);
+        if (claim === "live")
+            return result("cleanup-skipped", "a live session attached the checkout again");
+        if (claim === "unverifiable")
+            return result("cleanup-skipped", "the checkout's editing claim cannot be verified");
+        // Security: the command is the primary checkout's committed declaration, never a file of the task checkout being left.
+        const declared = await readCleanupDeclaration(join(startup, CLEANUP_DECLARATION));
+        if (declared === null)
+            return result("cleanup-unavailable", `this repository declares no cleanup command in ${CLEANUP_DECLARATION}; the checkout was retained`);
+        if (declared === "invalid")
+            return result("cleanup-unavailable", `${CLEANUP_DECLARATION} must hold {"cleanup": ["program", "argument", ...]}; the checkout was retained`);
+        const values = {
+            primary: startup, worktree: record.worktreeRoot, branch: record.branch,
+            change: record.change, pr: record.pr === undefined ? undefined : String(record.pr),
+        };
+        const missing = new Set();
+        const [command, ...arguments_] = declared.map(part => part.replace(/\{([a-z]+)\}/gu, (_match, name) => {
+            const value = values[name];
+            if (value === undefined)
+                missing.add(name);
+            return value ?? "";
+        }));
+        if (missing.size > 0 || command === undefined) {
+            return result("cleanup-unavailable", `the declared cleanup needs ${[...missing].map(name => `{${name}}`).join(" and ")}; run completion with the matching selector or the repository cleanup from primary`);
+        }
+        const run = options.run ?? execute;
+        try {
+            return result("cleanup-finished", bounded(await run(command, arguments_, startup, options.signal)));
+        }
+        catch (error) {
+            const output = isRecord(error) ? [error.stdout, error.stderr].filter(value => typeof value === "string" && value.length > 0).join("\n") : "";
+            return result("cleanup-failed", bounded(output || (error instanceof Error ? error.message : String(error))));
+        }
+    }
+    catch (error) {
+        return result("cleanup-skipped", error instanceof Error ? error.message : String(error));
+    }
+}
+/** The agent-facing account of a settled completion; the session is on the startup checkout in every case. */
+export function describeWorktreeCompletion(result) {
+    const headline = {
+        "cleanup-finished": "the repository cleanup command ran; its report below is authoritative",
+        "cleanup-failed": "the repository cleanup command failed; the checkout may remain and is retried with repository cleanup from primary",
+        "cleanup-unavailable": "cleanup is unavailable; the checkout was retained",
+        "cleanup-skipped": "cleanup was skipped; the checkout was retained",
+    };
+    return [
+        `Worktree completion (${result.kind}): ${headline[result.kind]}.`,
+        `Session uses ${result.startupRoot}; left ${result.cwd} (${result.branch}). Do not attach it again while cleanup is partial.`,
+        result.detail,
+    ].join("\n");
+}
+/** Null when the repository declares nothing; "invalid" when the declaration cannot be used as an argument list. */
+async function readCleanupDeclaration(path) {
+    const metadata = await lstat(path).catch(error => { if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+        return null; throw error; });
+    if (metadata === null)
+        return null;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+        return "invalid";
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        const cleanup = isRecord(value) ? value.cleanup : undefined;
+        return Array.isArray(cleanup) && cleanup.length > 0 && cleanup.length <= 64
+            && cleanup.every(part => typeof part === "string" && part.length > 0 && part.length <= 2_048 && !part.includes("\0"))
+            // Compatibility: the element check above establishes the string array.
+            ? cleanup : "invalid";
+    }
+    catch {
+        return "invalid";
+    }
+}
+async function readRecord(path) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size === 0 || metadata.size > MAX_RECORD_BYTES)
+            return null;
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!isRecord(value) || value.schema !== SCHEMA)
+            return null;
+        const text = (name) => typeof value[name] === "string" && value[name].length > 0 && value[name].length <= 32_768;
+        if (!["sessionId", "startupRoot", "commonDir", "worktreeRoot", "worktreeGitDir", "branch"].every(text))
+            return null;
+        if (typeof value.requestedAt !== "number" || !Number.isFinite(value.requestedAt))
+            return null;
+        if (value.change !== undefined && typeof value.change !== "string")
+            return null;
+        if (value.pr !== undefined && (typeof value.pr !== "number" || !Number.isSafeInteger(value.pr) || value.pr < 1))
+            return null;
+        // Compatibility: the checks above establish every field of the stored shape.
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function execute(command, arguments_, cwd, signal) {
+    const { execFile } = await import("node:child_process");
+    const { stdout } = await promisify(execFile)(command, [...arguments_], {
+        cwd, encoding: "utf8", windowsHide: true, timeout: CLEANUP_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, signal,
+    });
+    return stdout;
+}
+function bounded(text) {
+    const trimmed = text.trim();
+    return trimmed.length <= MAX_REPORT_CHARACTERS ? trimmed : `...${trimmed.slice(-MAX_REPORT_CHARACTERS)}`;
+}
+function samePath(left, right) {
+    const key = (value) => process.platform === "win32" ? resolve(value).toLowerCase() : resolve(value);
+    return key(left) === key(right);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function failure(code, message) {
+    return Object.assign(new Error(message), { code });
+}

package/dist/integrations/pi/engine/runtime-integration.js

@@ -142,7 +142,7 @@ export async function createPiRuntimeIntegration(options) {
                 services,
                 sessionManager: targetSessionManager,
                 ...(options.worktreeCwdReader === undefined ? {} : {
-                    customTools: createSessionWorktreeTools(cwd, signal => options.worktreeCwdReader(targetSessionManager.getSessionId(), targetSessionManager.getSessionFile(), signal ?? options.signal ?? new AbortController().signal)).filter(tool => !services.resourceLoader.getExtensions().extensions.some(extension => extension.tools.has(tool.name))),
+                    customTools: createSessionWorktreeTools(cwd, signal => options.worktreeCwdReader(targetSessionManager.getSessionId(), targetSessionManager.getSessionFile(), signal ?? options.signal ?? new AbortController().signal), options.worktreeCwdReader.settleShell === undefined ? undefined : signal => options.worktreeCwdReader.settleShell(targetSessionManager.getSessionId(), targetSessionManager.getSessionFile(), signal ?? options.signal ?? new AbortController().signal)).filter(tool => !services.resourceLoader.getExtensions().extensions.some(extension => extension.tools.has(tool.name))),
                 }),
                 ...(sessionStartEvent ? { sessionStartEvent } : {}),
                 ...(modelScope.model && !hasExistingSession ? { model: modelScope.model } : {}),

package/dist/integrations/pi/engine/worktree-tools.d.ts

@@ -1,4 +1,7 @@
 import { type ToolDefinition } from "../startup-public.js";
-export type PiWorktreeCwdReader = (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>;
+export type PiWorktreeCwdReader = ((sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string>) & {
+    /** Settles work a finished shell command left for the runtime; the text is appended to that command's result. */
+    readonly settleShell?: (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<string | null>;
+};
 /** Built-in tool definitions borrow the current attachment per call, without process-global chdir. */
-export declare function createSessionWorktreeTools(startupCwd: string, resolveCwd: (signal?: AbortSignal) => Promise<string>): ToolDefinition[];
+export declare function createSessionWorktreeTools(startupCwd: string, resolveCwd: (signal?: AbortSignal) => Promise<string>, settleShell?: (signal?: AbortSignal) => Promise<string | null>): ToolDefinition[];

package/dist/integrations/pi/engine/worktree-tools.js

@@ -1,20 +1,35 @@
 import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, defineTool, } from "../startup-public.js";
 /** Built-in tool definitions borrow the current attachment per call, without process-global chdir. */
-export function createSessionWorktreeTools(startupCwd, resolveCwd) {
+export function createSessionWorktreeTools(startupCwd, resolveCwd, settleShell) {
     function wrap(factory) {
         const definition = factory(startupCwd);
         return defineTool({
             ...definition,
             ...(definition.name === "bash" ? { promptGuidelines: [
                     ...(definition.promptGuidelines ?? []),
-                    "For task worktrees, use a1 worktree enter <branch> or a1 worktree attach <absolute-path>; success confirms attachment and subsequent built-in tools use that root. a1 worktree detach preserves files. Coordination and recovery are internal; no follow-up inventory check is required.",
+                    "For task worktrees, use a1 worktree enter <branch> or a1 worktree attach <absolute-path>; success confirms attachment and subsequent built-in tools use that root. a1 worktree detach preserves files. After a verified merge run a1 worktree complete instead of cleaning the attached checkout yourself; it returns this session to the startup checkout first and reports the repository cleanup result. Coordination and recovery are internal; no follow-up inventory check is required.",
                 ] } : {}),
             defaultActive: false,
             async execute(...args) {
                 const [id, params, signal, onUpdate, context] = args;
                 const cwd = await resolveCwd(signal);
                 signal?.throwIfAborted();
-                return await factory(cwd).execute(id, params, signal, onUpdate, { ...context, cwd });
+                if (definition.name !== "bash" || settleShell === undefined)
+                    return await factory(cwd).execute(id, params, signal, onUpdate, { ...context, cwd });
+                // Invariant: the shell has exited before settlement, so it no longer pins the checkout it was started in.
+                const settle = () => settleShell(signal).catch(error => `Worktree completion could not be settled: ${error instanceof Error ? error.message : String(error)}`);
+                let result;
+                try {
+                    result = await factory(cwd).execute(id, params, signal, onUpdate, { ...context, cwd });
+                }
+                catch (error) {
+                    const settled = await settle();
+                    if (settled !== null && error instanceof Error)
+                        error.message = `${error.message}\n\n${settled}`;
+                    throw error;
+                }
+                const settled = await settle();
+                return settled === null ? result : { ...result, content: [...result.content, { type: "text", text: settled }] };
             },
         });
     }

package/docs/architecture/project-structure.md

@@ -119,7 +119,7 @@ A1 owns creation/attachment, bounded retries, and ordinary recovery behind its w
 
 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.
 
-A1 attachment updates footer repository/PR discovery and subsequent built-in tool working directories without changing process-global cwd. Detach/disposal releases the runtime's claim and preserves Git data. An existing PR is not required. Explicit absolute paths retain their meaning; custom extensions and independent terminals keep their own cwd. Attachment never creates a Git lock, changes cleanup registration, or grants acceptance, finalization, merge, or deletion authority.
+A1 attachment updates footer repository/PR discovery and subsequent built-in tool working directories without changing process-global cwd. Detach/disposal releases the runtime's claim and preserves Git data. After a verified merge, `a1 worktree complete` detaches first and then runs the repository's configured cleanup from the startup checkout; an attachment whose checkout is gone is released automatically. An existing PR is not required. Explicit absolute paths retain their meaning; custom extensions and independent terminals keep their own cwd. Attachment never creates a Git lock, changes cleanup registration, or grants acceptance, finalization, merge, or deletion authority.
 
 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.
 

package/docs/features/worktrees.md

@@ -11,9 +11,10 @@ Run these commands through an active A1 session's shell tool:
 | `a1 worktree enter <type/short-description> [--base <branch>]` | Create or resume the matching task checkout and attach it. |
 | `a1 worktree attach <absolute-path>` | Attach an existing registered task checkout in this session's repository. |
 | `a1 worktree detach` | Release this session's attachment without deleting files or branches. |
+| `a1 worktree complete [--change <id>] [--pr <number>]` | After a verified merge: return this session to the startup checkout, then run the repository's configured cleanup. |
 | `a1 worktree list` | Informational same-repository inventory; never required after success. |
 
-Successful enter/attach returns the canonical root and branch after acquiring the editing claim. It is the complete attachment result: agents do not run a second inventory approval gate or implement their own retry loop. Temporary registration/coordination contention is retried within an operation budget. Actual ownership conflicts and uncertain records produce actionable failures rather than unsafe takeovers. A failed switch preserves the prior attachment. No command removes worktrees, branches, user files, or private workspace data.
+Successful enter/attach returns the canonical root and branch after acquiring the editing claim. It is the complete attachment result: agents do not run a second inventory approval gate or implement their own retry loop. Temporary registration/coordination contention is retried within an operation budget. Actual ownership conflicts and uncertain records produce actionable failures rather than unsafe takeovers. A failed switch preserves the prior attachment. No command removes worktrees, branches, user files, or private workspace data itself; `complete` only runs the cleanup command the repository declares.
 
 Enter creates `.worktrees/<short-description>` under the primary checkout. It fetches the selected origin base before creating a new topic branch. Base selection is explicit `--base`, local Git configuration `a1.worktreeBase`, then the origin default branch; local-only repositories fall back to the primary branch. Existing matching worktrees keep their local edits and history. Path/branch collisions, primary checkouts, foreign repositories, and Git-locked worktrees are retained, not forced or adopted. Setup commands, dependency installation, private-clone provisioning, and repository hooks are not executed by A1.
 
@@ -27,12 +28,39 @@ Background footer polling activates persisted claims once per session binding, t
 
 Implementation completion and review handoff do not end the task attachment. Keep it active for review and follow-up fixes so built-in tools and footer PR discovery continue using the task checkout. Detach only when explicitly requested or switching tasks; runtime shutdown releases editing claims automatically. Repository cleanup handoff is independent and does not require runtime detach.
 
+## Completing a merged task
+
+Never run repository cleanup against the checkout a session is attached to. The shell A1 starts for an attached session has that checkout as its working directory, and on Windows that pins the directory until the shell exits even after `cd`, so cleanup issued from it removes part of the checkout and then fails on the directory itself.
+
+`a1 worktree complete` sequences the two steps. In the issuing shell it only checks and detaches: the attachment must be valid and owned by this session, the checkout must not be locked in Git, and `git status` must show no tracked, staged, or untracked content. A blocker leaves the session attached and changes nothing. Otherwise the session returns to its startup checkout. Once that shell has exited, the A1 process runs the configured cleanup from the startup checkout and appends the outcome to the same command's result:
+
+| Outcome | Meaning |
+| --- | --- |
+| `cleanup-finished` | The cleanup command ran. Its report follows and is authoritative; A1 does not claim a removal itself. |
+| `cleanup-failed` | The command exited with an error. The checkout may remain; retry with the repository's cleanup from primary. |
+| `cleanup-unavailable` | The repository declares no command, or it needs `--change`/`--pr` that was not given. The checkout is retained. |
+| `cleanup-skipped` | Another live session attached the checkout, its claim is unverifiable, or the request was not settled within five minutes. |
+
+In every case the session is already on the startup checkout and its tools keep working. Do not attach a partially removed checkout again.
+
+The cleanup command is declared once in the repository, in a committed `.a1/worktree.json`, so no machine needs any setup:
+
+```json
+{ "cleanup": ["node", "scripts/governance/local-worktree-cleanup.mjs", "complete", "--repo", "{primary}", "--path", "{worktree}", "--change", "{change}", "--pr", "{pr}"] }
+```
+
+A1 reads the file from the primary checkout the session started in, never from the task checkout being left, so a task branch cannot change what runs until it is merged. The list is run without a shell from the primary checkout, with `{primary}`, `{worktree}`, `{branch}`, `{change}`, and `{pr}` substituted in each element; the first element must be a real executable such as `node`, not a `.cmd` shim. A repository without the file needs nothing: completion detaches, keeps the checkout, and reports `cleanup-unavailable`, and the repository's ordinary cleanup still applies. The command keeps every eligibility and deletion safeguard; A1 adds no deletion of its own. Delivery evidence is the command's to judge, so completing an unmerged task ends detached with the files intact and the command's blocker.
+
+## Invalid attachments
+
+If the attached checkout disappears, loses its Git pointer, or is replaced by a different worktree while the startup checkout still verifies, A1 releases this session's own association and editing claim. The built-in tool call that discovers it fails once with `worktree-attachment-invalid`, naming the released path and the startup checkout now in use, so work addressed to the lost checkout is never silently applied elsewhere. The next call runs from the startup checkout, and a resumed session recovers the same way. Uncertain results such as a timeout or an unverifiable startup checkout release nothing. `a1 worktree detach` works without validating the attached checkout. No file, branch, or other session's claim is removed.
+
 Claims coordinate participating A1 sessions. They are not a sandbox against arbitrary external editors, an editing lock in Git, repository cleanup ownership, or permission to merge/delete anything. Delivery and protected cleanup remain independent.
 
 ## Shared repository guidance
 
 Use this identical block in repositories, without adding another inventory approval gate:
 
-> In an active A1 session, use `a1 worktree enter <branch>` or `a1 worktree attach <absolute-path>`. Work in the returned directory; successful completion is the attachment confirmation. Keep the task attached after implementation completion and review handoff so follow-up fixes retain its checkout and PR. Use `a1 worktree detach` only when explicitly requested or switching tasks; it preserves files and branches. Runtime shutdown releases claims automatically. A1 owns coordination, retries, and recovery; `a1 worktree list` is informational. Outside A1, use ordinary Git worktrees.
+> In an active A1 session, use `a1 worktree enter <branch>` or `a1 worktree attach <absolute-path>`. Work in the returned directory; success is the attachment confirmation. Keep the task attached after implementation completion and review handoff so follow-up fixes retain its checkout and PR. After a verified merge, run `a1 worktree complete`: it returns the session to primary before repository cleanup runs, so never clean the attached checkout directly. Use `a1 worktree detach` only when explicitly requested or switching tasks; it preserves files and branches. Runtime shutdown releases claims automatically. A1 owns coordination, retries, and recovery; `a1 worktree list` is informational. Outside A1, use ordinary Git worktrees.
 
 Install an A1 release exposing this interface before integrating a repository's instruction migration. Older installations only expose the session-context aliases; unknown commands in those older releases may return quietly without performing an operation. A migration PR is not evidence that a compatible installed release is active.

package/docs/local-worktree-cleanup.md

@@ -103,6 +103,8 @@ An exact `complete` invocation may additionally use `--stop-dev-processes`. This
 cd /d/Git/a1 && node scripts/governance/local-worktree-cleanup.mjs complete --repo D:/Git/a1 --path D:/Git/a1/.worktrees/example-task --change example-change --pr 123 --stop-dev-processes
 ```
 
+Inside an A1 session attached to the candidate, do not run this command yourself: run `a1 worktree complete --change example-change --pr 123`, which returns the session to primary and then runs this same command as declared in the repository's `.a1/worktree.json` (see [worktree commands](features/worktrees.md#completing-a-merged-task)). `complete`, sweep, and the queue report `blocked` with `attached-session` while a running A1 session still has the checkout attached, and `attached-session-unverifiable` when that checkout's claim record cannot be read; the check reads A1's claim record only, changes nothing, and needs no A1 installation. Explicit `discard` and `retire-redundant` do not yet apply it.
+
 Agents do not manually remove generated content, call `git worktree remove`, or delete the local branch after delivery. The JSON result is authoritative: report success only for `removed` or verified `already-absent`; otherwise retain the worktree and report the exact blocker. A handed-off entry whose worktree was deleted by hand completes through its journal, and its branch is deleted under the accepted-ancestry rule. Legacy roles can supply separate `--source-pr`, `--candidate-pr`, and `--role` values.
 
 ## Explicit closed-unmerged discard
@@ -319,7 +321,7 @@ Disable writes a stop sentinel without waiting for a busy state or resource lock
 Dependency-free focused fixtures (temporary repositories only, no live PR mutation or watcher activation):
 
 ```bash
-node --test test/repository-governance/local-cleanup.node.mjs test/repository-governance/local-cleanup-evidence.node.mjs test/repository-governance/local-cleanup-watch.node.mjs
+node --test test/repository-governance/local-cleanup.node.mjs test/repository-governance/local-cleanup-evidence.node.mjs test/repository-governance/local-cleanup-watch.node.mjs test/repository-governance/local-cleanup-attachment.node.mjs
 ```
 
 The Vitest bridge includes these fixtures in ordinary fast CI, whose runner is Windows. On Windows the suite exercises an actual exclusive file handle and a junction; a non-Windows run explicitly skips the Windows-only handle case rather than claiming it passed. The handle fixture starts one throwaway `powershell.exe` when the file loads so the hosted runner's interpreter cold start overlaps the earlier tests instead of the fixture's timed hold; its bounds and release protocol are unchanged. Required current-head CI and a separately authorized live archive lifecycle remain necessary before acceptance; fixtures and preview do not replace those gates.

package/docs/openspec-archive-automation.md

@@ -306,7 +306,7 @@ After version-3 merge, verify:
 - the declared archive, conditional manifest, and synchronized specs match their digests; and
 - the unchanged remote topic ref is absent.
 
-Only then shall the owning agent invoke the exact-candidate `complete` operation documented in [local cleanup](local-worktree-cleanup.md) from the primary checkout. The command owns registration/release, repository-generated disposables, one bounded evidence pass, non-force worktree removal, and unchanged local-ref cleanup; agents do not manually delete generated content, worktrees, or branches. Version 3 uses the implementation PR as both source and candidate and does not wait for nonexistent acceptance/archive PRs.
+Only then shall the owning agent invoke the exact-candidate `complete` operation documented in [local cleanup](local-worktree-cleanup.md) from the primary checkout. An A1 session still attached to that checkout uses `a1 worktree complete --change <change> --pr <pr>` instead, which leaves the checkout before the same operation runs. The command owns registration/release, repository-generated disposables, one bounded evidence pass, non-force worktree removal, and unchanged local-ref cleanup; agents do not manually delete generated content, worktrees, or branches. Version 3 uses the implementation PR as both source and candidate and does not wait for nonexistent acceptance/archive PRs.
 
 Closing an unmerged PR does not by itself authorize local or remote deletion. After explicit candidate-specific rejection and remote-deletion confirmation, the repository-owned local `discard` command may compare-and-delete only that closed-unmerged PR's exact unchanged same-repository unprotected topic ref, then apply the ordinary non-force local safeguards. Automatic remote cleanup remains merge-only and never touches local worktrees.
 

package/docs/worktree-link-recovery.md

@@ -33,5 +33,7 @@ When the old gate is absent, updated A1 initializes its compatibility barrier au
 | `session-runtime-unverifiable` | The runtime's recorded process cannot be checked. Retry; 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. |
+| `worktree-attachment-invalid` | The attached checkout is gone or replaced. A1 released this session's attachment; retry the call from the startup checkout. |
+| `worktree-not-attached` / `worktree-content` | Completion needs an attached checkout without uncommitted or untracked content. Nothing was changed. |
 
 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.1287",
+  "version": "0.2.7-dev.1288",
   "description": "Standalone single-agent terminal UI on pinned Pi",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -113,7 +113,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "df8f3fea78404f0413ce40de8d39b7102ead643a",
-    "pullRequest": 914
+    "source": "bfbed9a4849fe7ba1b6a879cef7a800a132e18e9",
+    "pullRequest": 915
   }
 }