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

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

@@ -2,10 +2,14 @@ export { assertLaunchProfileId } from "./model.js";
 export type { LaunchProfileId, ProcessIdentity } from "./model.js";
 export { PID_LIVENESS_IDENTITY, inspectLiveProcess } from "./process-liveness.js";
 export { resolveProductPaths } from "./paths.js";
+export { serveSessionControl, requestSessionControl } from "./session-control.js";
+export type { SessionControlHostOptions, SessionControlIdentity, SessionControlRequestOptions } from "./session-control.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

@@ -1,7 +1,9 @@
 export { assertLaunchProfileId } from "./model.js";
 export { PID_LIVENESS_IDENTITY, inspectLiveProcess } from "./process-liveness.js";
 export { resolveProductPaths } from "./paths.js";
+export { serveSessionControl, requestSessionControl } from "./session-control.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-control.d.ts

@@ -0,0 +1,26 @@
+import type { ProcessIdentity } from "./model.js";
+export interface SessionControlIdentity {
+    readonly sessionId: string;
+    readonly binding: number;
+}
+interface ControlOptions {
+    readonly runtimeDir: string;
+    readonly inspectProcess?: (pid: number) => Promise<ProcessIdentity | null>;
+}
+export interface SessionControlHostOptions extends ControlOptions {
+    readonly runtimeId: string;
+    readonly identity: () => SessionControlIdentity;
+    readonly handle: (payload: unknown) => Promise<unknown>;
+}
+export interface SessionControlRequestOptions extends ControlOptions {
+    readonly sessionId: string;
+    readonly runtimeId?: string;
+    readonly payload: unknown;
+    readonly timeoutMs?: number;
+}
+export declare function serveSessionControl(options: SessionControlHostOptions): Promise<{
+    publish(): Promise<void>;
+    dispose(): Promise<void>;
+}>;
+export declare function requestSessionControl(options: SessionControlRequestOptions): Promise<unknown>;
+export {};

package/dist/foundation/lifecycle/session-control.js

@@ -0,0 +1,222 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readdir, open, realpath, rename, unlink, writeFile, chmod } from "node:fs/promises";
+import { createConnection, createServer } from "node:net";
+import { join, resolve } from "node:path";
+import { inspectLiveProcess } from "./process-liveness.js";
+const LIMIT = 8192;
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/iu;
+const SLUG = /^[a-z0-9-]{1,128}$/iu;
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const hash = (value) => createHash("sha256").update(value).digest("hex").slice(0, 32);
+const address = (directory, id) => process.platform === "win32"
+    ? `\\\\.\\pipe\\session-control-${hash(directory)}-${id}` : join(directory, `${id}.sock`);
+async function privateDirectory(runtimeDir, create) {
+    const selectedRoot = resolve(runtimeDir);
+    if (create)
+        await mkdir(selectedRoot, { recursive: true, mode: 0o700 });
+    const root = await realpath(selectedRoot);
+    const directory = join(root, "session-controls");
+    if (create)
+        await mkdir(directory, { mode: 0o700 }).catch(error => { if (error.code !== "EEXIST")
+            throw error; });
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || resolve(await realpath(directory)) !== directory) {
+        throw fail("control-boundary", "Session control directory is not a private regular directory.");
+    }
+    if (process.platform !== "win32" && (stat.mode & 0o077) !== 0)
+        throw fail("control-boundary", "Session control directory permissions are not private.");
+    return directory;
+}
+async function readRegistration(file) {
+    const stat = await lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > LIMIT || (process.platform !== "win32" && (stat.mode & 0o077) !== 0)) {
+        throw fail("control-boundary", "Invalid session control record.");
+    }
+    const handle = await open(file, "r");
+    let raw;
+    try {
+        const opened = await handle.stat();
+        if (opened.dev !== stat.dev || opened.ino !== stat.ino || !opened.isFile())
+            throw fail("control-boundary", "Session control record changed during lookup.");
+        const buffer = Buffer.alloc(LIMIT + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > LIMIT)
+            throw fail("control-boundary", "Session control record exceeds the size limit.");
+        raw = buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw fail("control-boundary", "Malformed session control record.");
+    }
+    if (!value || typeof value !== "object")
+        throw fail("control-boundary", "Malformed session control record.");
+    if (value.version !== 1 || !UUID.test(value.id) || !UUID.test(value.sessionId) || typeof value.runtimeId !== "string" || !SLUG.test(value.runtimeId)
+        || !UUID.test(value.nonce) || !Number.isSafeInteger(value.binding) || value.binding < 0
+        || !Number.isSafeInteger(value.owner?.pid) || value.owner.pid <= 0 || typeof value.owner.startIdentity !== "string") {
+        throw fail("control-boundary", "Malformed session control record.");
+    }
+    return value;
+}
+function receive(socket, consume) {
+    let data = "", complete = false;
+    socket.setEncoding("utf8");
+    socket.on("data", chunk => {
+        if (complete) {
+            socket.destroy();
+            return;
+        }
+        data += chunk;
+        if (Buffer.byteLength(data) > LIMIT) {
+            socket.destroy();
+            return;
+        }
+        const newline = data.indexOf("\n");
+        if (newline < 0)
+            return;
+        complete = true;
+        if (data.slice(newline + 1).trim() !== "") {
+            socket.destroy();
+            return;
+        }
+        try {
+            consume(JSON.parse(data.slice(0, newline)));
+        }
+        catch {
+            socket.destroy();
+        }
+    });
+}
+export async function serveSessionControl(options) {
+    if (!SLUG.test(options.runtimeId))
+        throw fail("session-unavailable", "Runtime identity is invalid.");
+    const directory = await privateDirectory(options.runtimeDir, true);
+    const inspect = options.inspectProcess ?? inspectLiveProcess;
+    const owner = await inspect(process.pid);
+    if (!owner || owner.pid !== process.pid || !owner.startIdentity)
+        throw fail("session-unavailable", "Runtime identity cannot be verified.");
+    const id = randomUUID(), nonce = randomUUID(), file = join(directory, `${id}.json`);
+    let disposed = false, queue = Promise.resolve(), publication = Promise.resolve();
+    const sockets = new Set();
+    const server = createServer(socket => {
+        sockets.add(socket);
+        socket.setTimeout(5000, () => socket.destroy());
+        socket.on("error", () => { });
+        socket.on("close", () => sockets.delete(socket));
+        receive(socket, input => {
+            queue = queue.then(async () => {
+                try {
+                    const request = input;
+                    const current = options.identity();
+                    if (disposed || socket.destroyed || request.nonce !== nonce || request.runtimeId !== options.runtimeId
+                        || request.sessionId !== current.sessionId || request.binding !== current.binding) {
+                        throw fail("session-unavailable", "The selected session is no longer active.");
+                    }
+                    if (!UUID.test(request.requestId) || !Number.isFinite(request.deadline) || request.deadline <= Date.now() || request.deadline > Date.now() + 5000) {
+                        throw fail("request-expired", "Session request expired before application.");
+                    }
+                    // Concurrency: no await separates the identity/deadline check from calling the live handler.
+                    const result = await options.handle(request.payload);
+                    if (!socket.destroyed)
+                        socket.end(`${JSON.stringify({ requestId: request.requestId, result })}\n`);
+                }
+                catch (error) {
+                    const failure = error;
+                    if (!socket.destroyed)
+                        socket.end(`${JSON.stringify({ error: { code: failure.code ?? "control-failed", message: failure.message } })}\n`);
+                }
+            }).catch(() => { socket.destroy(); });
+        });
+    });
+    await new Promise((done, reject) => { server.once("error", reject); server.listen(address(directory, id), () => { server.off("error", reject); done(); }); });
+    server.on("error", () => { });
+    server.maxConnections = 64;
+    const publish = () => {
+        publication = publication.catch(() => { }).then(async () => {
+            if (disposed)
+                return;
+            const identity = options.identity();
+            if (!UUID.test(identity.sessionId) || !Number.isSafeInteger(identity.binding) || identity.binding < 0)
+                throw fail("session-unavailable", "Session identity is not available.");
+            const temporary = join(directory, `${id}.${randomUUID()}.tmp`);
+            try {
+                await writeFile(temporary, JSON.stringify({ version: 1, id, nonce, runtimeId: options.runtimeId, owner, ...identity }), { mode: 0o600, flag: "wx" });
+                await rename(temporary, file);
+            }
+            finally {
+                await unlink(temporary).catch(() => { });
+            }
+        });
+        return publication;
+    };
+    const dispose = async () => {
+        if (disposed)
+            return;
+        disposed = true;
+        for (const socket of sockets)
+            socket.destroy();
+        await new Promise(done => server.close(() => done()));
+        await queue;
+        await publication.catch(() => { });
+        await unlink(file).catch(() => { });
+    };
+    try {
+        if (process.platform !== "win32")
+            await chmod(address(directory, id), 0o600);
+        await publish();
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+    return { publish, dispose };
+}
+export async function requestSessionControl(options) {
+    if (!UUID.test(options.sessionId))
+        throw fail("invalid-session", "Supply a complete session UUID.");
+    const budget = Math.min(5000, Math.max(1, options.timeoutMs ?? 3000));
+    const deadline = Date.now() + budget;
+    const directory = await privateDirectory(options.runtimeDir, false).catch(() => { throw fail("session-unavailable", "No live session control is available."); });
+    const names = (await readdir(directory)).filter(name => UUID.test(name.slice(0, -5)) && name.endsWith(".json"));
+    if (names.length > 256)
+        throw fail("control-limit", "Too many session records to resolve safely.");
+    const matches = [];
+    for (const name of names) {
+        const record = await readRegistration(join(directory, name)).catch(error => { if (error.code === "ENOENT")
+            return null; throw error; });
+        if (record === null || `${record.id}.json` !== name || record.sessionId !== options.sessionId || (options.runtimeId !== undefined && record.runtimeId !== options.runtimeId))
+            continue;
+        const owner = await (options.inspectProcess ?? inspectLiveProcess)(record.owner.pid);
+        if (owner?.startIdentity === record.owner.startIdentity)
+            matches.push(record);
+        if (Date.now() >= deadline)
+            throw fail("request-expired", "Session lookup exceeded its deadline.");
+    }
+    if (matches.length !== 1)
+        throw fail(matches.length > 1 ? "ambiguous-session" : "session-unavailable", "Select one running bare session by its complete session id.");
+    const record = matches[0];
+    return await new Promise((done, reject) => {
+        const socket = createConnection(address(directory, record.id));
+        const requestId = randomUUID();
+        const timer = setTimeout(() => { socket.destroy(); reject(fail("request-expired", "Session request timed out; application was not acknowledged.")); }, Math.max(1, deadline - Date.now()));
+        const finish = () => { clearTimeout(timer); socket.destroy(); };
+        socket.on("error", () => { finish(); reject(fail("session-unavailable", "The selected session could not be reached.")); });
+        socket.on("close", () => { clearTimeout(timer); reject(fail("session-unavailable", "The selected session closed before acknowledgement.")); });
+        socket.on("connect", () => socket.write(`${JSON.stringify({ ...record, requestId, deadline, payload: options.payload })}\n`));
+        receive(socket, input => {
+            const response = input;
+            finish();
+            if (response.error)
+                reject(fail(response.error.code, response.error.message));
+            else if (response.requestId !== requestId)
+                reject(fail("control-failed", "Session acknowledgement did not match the request."));
+            else
+                done(response.result);
+        });
+    });
+}

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;