@nurix/nustack 0.10.0-dev.19 → 0.10.0-dev.21

package/dist/commands/review.js

@@ -8,16 +8,30 @@ const EXIT_FOR = {
     none: 1,
     unreachable: 2,
 };
+const latestAnswered = (items) => items.find((item) => item.answer?.verdict === "signed" || item.answer?.verdict === "refused");
 export function decisionStateOf(items) {
-    const latest = items.find((item) => item.answer?.verdict === "signed" || item.answer?.verdict === "refused");
+    const latest = latestAnswered(items);
     if (!latest)
         return "none";
     return latest.answer?.verdict === "signed" ? "signed" : "refused";
 }
-function checkLine(state, commit) {
+export function waivedKeysOf(items) {
+    const latest = latestAnswered(items);
+    if (latest?.answer?.verdict !== "signed")
+        return [];
+    const waivers = latest.answer.waivers;
+    if (!Array.isArray(waivers))
+        return [];
+    return waivers
+        .map((waiver) => waiver?.criterionKey)
+        .filter((key) => typeof key === "string" && key.length > 0);
+}
+function checkLine(state, commit, waived) {
     switch (state) {
         case "signed":
-            return `review check: ${commit} is signed off\n`;
+            return waived.length
+                ? `review check: ${commit} is signed off — ${waived.length} ${waived.length === 1 ? "criterion" : "criteria"} waived: ${waived.join(", ")}\n`
+                : `review check: ${commit} is signed off\n`;
         case "refused":
             return `review check: ${commit} was refused\n`;
         case "none":
@@ -34,11 +48,11 @@ export async function runReviewCheck(options, globals) {
         process.exitCode = 2;
         return;
     }
-    const report = (state) => {
+    const report = (state, waived = []) => {
         if (json)
-            printJsonSuccess("review check", { commit, state, exitCode: EXIT_FOR[state] });
+            printJsonSuccess("review check", { commit, state, exitCode: EXIT_FOR[state], waived });
         else
-            process.stdout.write(checkLine(state, commit));
+            process.stdout.write(checkLine(state, commit, waived));
         process.exitCode = EXIT_FOR[state];
     };
     const baseUrl = resolveNuStackUrl(globals);
@@ -47,7 +61,7 @@ export async function runReviewCheck(options, globals) {
         return report("unreachable");
     try {
         const items = await makeReviewClient(baseUrl, deviceAuth.accessToken).readDecisions(commit, options.repository?.trim() || null);
-        report(decisionStateOf(items));
+        report(decisionStateOf(items), waivedKeysOf(items));
     }
     catch (error) {
         if (error instanceof ReviewUnreachableError)

package/dist/commands/sessions.js

@@ -1,10 +1,15 @@
 import { readFile } from "node:fs/promises";
+import path from "node:path";
+import * as p from "@clack/prompts";
 import { ensureAccessToken } from "../lib/auth_grant.js";
+import { isInteractive } from "../lib/interactive.js";
 import { resolveNuStackUrl } from "../lib/nustack_client.js";
 import { makeSessionsClient, sessionsClientFromEnv } from "../lib/sessions/client.js";
 import { recordOutsideSessions, } from "../lib/sessions/outsideSessions.js";
+import { inspectSession, readOrphanedWorktrees, reclaimSession, } from "../lib/session-engine/prune.js";
+import { readSessionRegistry, sessionRegistryPath } from "../lib/session-engine/registry.js";
 import { SessionSupervisor } from "../lib/session-engine/supervisor.js";
-import { printJsonSuccess } from "../lib/json_output.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
 export async function runSessionsServe(engineVersion) {
     const supervisor = new SessionSupervisor({
         input: process.stdin,
@@ -75,3 +80,134 @@ export async function runSessionsRecord(options, globals) {
     });
     report("sessions record", summary, json);
 }
+async function readSessions() {
+    const { records, dropped } = await readSessionRegistry();
+    const orphans = await readOrphanedWorktrees();
+    const sessions = [];
+    for (const record of [...records, ...orphans.records]) {
+        sessions.push({ record, facts: await inspectSession(record) });
+    }
+    return { sessions, unreadable: dropped, undecipherableOrphans: orphans.undecipherable };
+}
+function statusWord(entry) {
+    if (entry.facts.orphaned)
+        return "orphaned";
+    if (entry.facts.stale)
+        return "stale";
+    return entry.record.status;
+}
+function formatSessionRow(entry) {
+    const checkout = path.basename(entry.record.projectPath);
+    return (`${entry.record.sessionId.padEnd(38)} ${checkout.padEnd(22)} ${(entry.record.branch ?? "—").padEnd(31)} ` +
+        `${statusWord(entry).padEnd(10)} ${entry.facts.reason}`);
+}
+function toJsonView(entry) {
+    const { record, facts } = entry;
+    return {
+        sessionId: record.sessionId,
+        projectPath: record.projectPath,
+        worktreePath: record.worktreePath,
+        branch: record.branch,
+        status: record.status,
+        nustack: record.nustack,
+        createdAt: record.createdAt,
+        closedAt: record.closedAt ?? null,
+        permissionMode: record.permissionMode ?? null,
+        baseBranch: record.baseBranch ?? null,
+        isolated: facts.isolated,
+        checkoutPresent: facts.checkoutPresent,
+        worktreePresent: facts.worktreePresent,
+        branchExists: facts.branchExists,
+        reading: facts.reading,
+        dirty: facts.dirty,
+        stale: facts.stale,
+        orphaned: facts.orphaned,
+        reclaimable: facts.reclaimable,
+        reason: facts.reason,
+    };
+}
+export async function runSessionsList(options) {
+    const json = options.json === true;
+    const { sessions, unreadable, undecipherableOrphans } = await readSessions();
+    if (json) {
+        printJsonSuccess("sessions list", {
+            registryPath: sessionRegistryPath(),
+            unreadable,
+            undecipherableOrphans,
+            sessions: sessions.map(toJsonView),
+        });
+        return;
+    }
+    if (sessions.length === 0 && unreadable === 0 && undecipherableOrphans.length === 0) {
+        console.log("No engine-opened sessions on this machine.");
+        return;
+    }
+    if (sessions.length > 0) {
+        console.log(`${"SESSION".padEnd(38)} ${"CHECKOUT".padEnd(22)} ${"BRANCH".padEnd(31)} ${"STATUS".padEnd(10)} HOLDS`);
+        for (const entry of sessions)
+            console.log(formatSessionRow(entry));
+    }
+    if (unreadable > 0)
+        console.log(`${unreadable} row(s) in the registry could not be read and were skipped.`);
+    for (const orphan of undecipherableOrphans) {
+        console.log(`1 worktree under the pre-rename engine home names no checkout and must be removed by hand: ${orphan}.`);
+    }
+}
+function previewLine(entry) {
+    const verb = entry.facts.reclaimable ? "reclaim" : "refuse";
+    return `  ${verb}  ${entry.record.sessionId}  ${entry.record.branch ?? "—"}  — ${entry.facts.reason}`;
+}
+export async function runSessionsPrune(options) {
+    const json = options.json === true;
+    const force = options.force === true;
+    const { sessions } = await readSessions();
+    const scoped = options.session ? sessions.filter((entry) => entry.record.sessionId === options.session) : sessions;
+    if (options.session && scoped.length === 0) {
+        const message = `No session ${options.session} in this machine's registry — pass one from \`nustack sessions list\`.`;
+        if (json)
+            return printJsonError("sessions prune", { code: "SESSION_NOT_FOUND", message });
+        p.log.error(message);
+        process.exitCode = 1;
+        return;
+    }
+    const candidates = scoped.filter((entry) => force || entry.facts.reclaimable);
+    if (options.yes !== true) {
+        const plan = candidates.map((entry) => ({
+            sessionId: entry.record.sessionId,
+            branch: entry.record.branch,
+            worktreePath: entry.record.worktreePath,
+            orphaned: entry.facts.orphaned,
+            reclaimable: entry.facts.reclaimable,
+            reason: entry.facts.reason,
+        }));
+        if (json)
+            return printJsonSuccess("sessions prune", { applied: false, plan, note: "preview only — pass --yes to apply" });
+        if (plan.length === 0) {
+            console.log("Nothing to reclaim.");
+            return;
+        }
+        console.log(`Would reclaim ${plan.length} session(s):`);
+        for (const entry of candidates)
+            console.log(previewLine(entry));
+        if (!isInteractive()) {
+            console.log("Preview only — re-run with --yes to apply.");
+            return;
+        }
+        const answer = await p.confirm({ message: "Remove these worktrees and delete their branches?" });
+        if (p.isCancel(answer) || !answer) {
+            p.outro("Cancelled — nothing reclaimed.");
+            return;
+        }
+    }
+    const reclaimed = [];
+    const refused = [];
+    for (const entry of candidates) {
+        const outcome = await reclaimSession(entry.record, { force });
+        (outcome.reason === null ? reclaimed : refused).push(outcome);
+    }
+    if (json)
+        return printJsonSuccess("sessions prune", { applied: true, reclaimed, refused });
+    console.log(`Reclaimed ${reclaimed.length} session(s); refused ${refused.length}.`);
+    for (const outcome of refused)
+        console.log(`  refused  ${outcome.sessionId} — ${outcome.reason ?? "unknown"}`);
+}

package/dist/index.js

@@ -24,7 +24,7 @@ import { runOrganizationList, runOrganizationCreate, runOrganizationUse } from "
 import { runDocsList, runDocsShow, runDocsStatus } from "./commands/docs.js";
 import { runHandoffList, runHandoffShow } from "./commands/handoff.js";
 import { runToolkitStatus, runToolkitReconcile } from "./commands/toolkit.js";
-import { runSessionsRecord, runSessionsServe } from "./commands/sessions.js";
+import { runSessionsList, runSessionsPrune, runSessionsRecord, runSessionsServe, } from "./commands/sessions.js";
 import { registerReviewCommands } from "./commands/review.js";
 import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
 import { printJsonError } from "./lib/json_output.js";
@@ -262,6 +262,19 @@ sessions
     .option("--scan <json>", "the scan payload as JSON, or @<path> to read it from a file")
     .option("--json", "emit the versioned machine envelope")
     .action(async (options) => runSessionsRecord(options, program.opts()));
+sessions
+    .command("list")
+    .description("List the sessions this machine's engine opened, and what each one's worktree and branch still hold")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runSessionsList(options));
+sessions
+    .command("prune")
+    .description("Reclaim the worktree and branch of a session that has ended (preview unless --yes)")
+    .option("--session <id>", "reclaim one session instead of every reclaimable one")
+    .option("--yes", "apply the preview without prompting")
+    .option("--force", "also reclaim an unmerged or dirty session — never one whose engine is running")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runSessionsPrune(options));
 const toolkit = program.command("toolkit").description("Inspect and reconcile the Project's toolkit pin");
 toolkit
     .command("status")

package/dist/lib/session-engine/frames.js

@@ -5,6 +5,8 @@ const INBOUND_TYPES = new Set([
     "session.approval",
     "session.interrupt",
     "session.close",
+    "session.list",
+    "session.reclaim",
     "engine.shutdown",
 ]);
 export function parseInboundFrame(line) {
@@ -31,6 +33,7 @@ export function parseInboundFrame(line) {
     const requireString = (key) => (typeof frame[key] === "string" && frame[key] !== "" ? frame[key] : null);
     switch (type) {
         case "engine.shutdown":
+        case "session.list":
             return { ok: true, frame: { v: FRAME_VERSION, type } };
         case "session.open": {
             const sessionId = requireString("sessionId");
@@ -40,7 +43,12 @@ export function parseInboundFrame(line) {
             const permissionMode = typeof frame.permissionMode === "string" ? frame.permissionMode : undefined;
             const isolated = frame.isolated === true ? true : undefined;
             const resumeSessionId = typeof frame.resumeSessionId === "string" && frame.resumeSessionId !== "" ? frame.resumeSessionId : undefined;
-            return { ok: true, frame: { v: FRAME_VERSION, type, sessionId, projectPath, permissionMode, isolated, resumeSessionId } };
+            const rawCommit = typeof frame.commit === "string" ? frame.commit : null;
+            if (rawCommit !== null && !/^[0-9a-f]{7,64}$/.test(rawCommit)) {
+                return { ok: false, error: { code: "BAD_FRAME", name: type, message: "session.open commit must be a hex object name" } };
+            }
+            const commit = rawCommit ?? undefined;
+            return { ok: true, frame: { v: FRAME_VERSION, type, sessionId, projectPath, permissionMode, isolated, commit, resumeSessionId } };
         }
         case "session.turn": {
             const sessionId = requireString("sessionId");
@@ -58,7 +66,8 @@ export function parseInboundFrame(line) {
             return { ok: true, frame: { v: FRAME_VERSION, type, sessionId, requestId, verdict } };
         }
         case "session.interrupt":
-        case "session.close": {
+        case "session.close":
+        case "session.reclaim": {
             const sessionId = requireString("sessionId");
             if (!sessionId)
                 return { ok: false, error: { code: "BAD_FRAME", name: type, message: `${type} requires sessionId` } };

package/dist/lib/session-engine/prune.js

@@ -0,0 +1,233 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { updateSessionRegistry } from "./registry.js";
+import { ENGINE_SESSION_BRANCH_PREFIX, LEGACY_ENGINE_BRANCH_PREFIX, gitOutcome, legacyEngineHome, sessionsHome, } from "./worktree.js";
+const NOT_ISOLATED = "the session ran in the checkout itself — there is nothing of its own to reclaim";
+const FOREIGN_BRANCH = "its branch is not an engine session branch — this row is not the engine's to reclaim";
+const FOREIGN_WORKTREE = "its worktree is outside the engine's worktrees directory — this row is not the engine's to reclaim";
+function insideAnEngineHome(worktreePath, env) {
+    const live = path.join(sessionsHome(env), "worktrees") + path.sep;
+    const legacy = path.join(legacyEngineHome(env), "worktrees") + path.sep;
+    return worktreePath.startsWith(live) || worktreePath.startsWith(legacy);
+}
+function isEngineBranch(branch) {
+    return branch !== null && (branch.startsWith(ENGINE_SESSION_BRANCH_PREFIX) || branch.startsWith(LEGACY_ENGINE_BRANCH_PREFIX));
+}
+async function isDirectory(target) {
+    try {
+        return (await stat(target)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function refuse(record, facts, reason) {
+    return {
+        sessionId: record.sessionId,
+        isolated: false,
+        checkoutPresent: false,
+        worktreePresent: false,
+        branchExists: false,
+        reading: "unknown",
+        dirty: false,
+        stale: false,
+        orphaned: false,
+        reclaimable: false,
+        ...facts,
+        reason,
+    };
+}
+function processIsGone(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+export async function inspectSession(record, env = process.env) {
+    const orphaned = record.worktreePath.startsWith(path.join(legacyEngineHome(env), "worktrees") + path.sep);
+    const checkoutPresent = await isDirectory(record.projectPath);
+    const worktreePresent = await isDirectory(record.worktreePath);
+    const isolated = record.branch !== null && record.worktreePath !== record.projectPath;
+    if (!isolated)
+        return refuse(record, { checkoutPresent, orphaned }, NOT_ISOLATED);
+    if (!isEngineBranch(record.branch))
+        return refuse(record, { isolated, checkoutPresent, orphaned }, FOREIGN_BRANCH);
+    if (!insideAnEngineHome(record.worktreePath, env)) {
+        return refuse(record, { isolated, checkoutPresent, orphaned }, FOREIGN_WORKTREE);
+    }
+    if (!checkoutPresent) {
+        return refuse(record, { isolated, worktreePresent, orphaned }, `its checkout is gone — remove ${record.worktreePath} and the branch by hand`);
+    }
+    const branch = record.branch;
+    const branchExists = (await gitOutcome(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], record.projectPath)).ok;
+    const dirty = worktreePresent && (await gitOutcome(["status", "--porcelain"], record.worktreePath)).stdout !== "";
+    const stale = record.status === "open" && typeof record.enginePid === "number" && processIsGone(record.enginePid);
+    const reading = await readMerge(record, branch, branchExists, dirty);
+    const reclaimable = checkoutPresent &&
+        !dirty &&
+        (record.status === "closed" || stale) &&
+        (reading === "untouched" || reading === "merged" || reading === "merged-into-head" || !branchExists);
+    return {
+        sessionId: record.sessionId,
+        isolated,
+        checkoutPresent,
+        worktreePresent,
+        branchExists,
+        reading,
+        dirty,
+        stale,
+        orphaned,
+        reclaimable,
+        reason: explain({ reading, dirty, stale, branchExists, reclaimable, status: record.status, baseBranch: record.baseBranch ?? null }),
+    };
+}
+async function readMerge(record, branch, branchExists, dirty) {
+    if (!branchExists)
+        return "unknown";
+    const cwd = record.projectPath;
+    if (record.baseCommit) {
+        const tip = await gitOutcome(["rev-parse", branch], cwd);
+        if (tip.ok && tip.stdout === record.baseCommit && !dirty)
+            return "untouched";
+    }
+    if (record.baseBranch) {
+        const againstBase = await gitOutcome(["merge-base", "--is-ancestor", branch, record.baseBranch], cwd);
+        if (againstBase.code === 0)
+            return "merged";
+        if (againstBase.code === 1)
+            return "unmerged";
+    }
+    const againstHead = await gitOutcome(["merge-base", "--is-ancestor", branch, "HEAD"], cwd);
+    if (againstHead.code === 0)
+        return "merged-into-head";
+    if (againstHead.code === 1)
+        return "unmerged";
+    return "unknown";
+}
+function explain(facts) {
+    if (facts.dirty)
+        return "its worktree has uncommitted changes — commit or discard them first";
+    if (facts.status === "open" && !facts.stale)
+        return "it is still open — close the session first";
+    if (facts.reading === "unmerged")
+        return "unmerged — its branch has work nothing has taken";
+    if (facts.reading === "unknown" && facts.branchExists)
+        return "its branch could not be read against any base";
+    if (!facts.reclaimable)
+        return "it cannot be reclaimed yet";
+    if (!facts.branchExists)
+        return "its branch is already gone — only the worktree is left";
+    if (facts.reading === "untouched")
+        return "nothing was ever done in this session, and its worktree is clean";
+    if (facts.reading === "merged")
+        return `merged into ${facts.baseBranch ?? "its base"} and its worktree is clean`;
+    return "merged into the checkout's current HEAD and its worktree is clean";
+}
+export async function readOrphanedWorktrees(env = process.env) {
+    const root = path.join(legacyEngineHome(env), "worktrees");
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch {
+        return { records: [], undecipherable: [] };
+    }
+    const records = [];
+    const undecipherable = [];
+    for (const id of entries) {
+        const worktreePath = path.join(root, id);
+        const projectPath = await checkoutOfLinkedWorktree(worktreePath, id);
+        if (!projectPath) {
+            undecipherable.push(worktreePath);
+            continue;
+        }
+        records.push({
+            sessionId: id,
+            projectPath,
+            worktreePath,
+            branch: `${LEGACY_ENGINE_BRANCH_PREFIX}${id}`,
+            provider: "claude-code",
+            providerSessionId: null,
+            createdAt: await directoryCreatedAt(worktreePath),
+            status: "closed",
+            nustack: 1,
+            projectId: null,
+            permissionMode: null,
+            baseBranch: null,
+            baseCommit: null,
+            enginePid: null,
+            closedAt: null,
+        });
+    }
+    return { records, undecipherable };
+}
+async function checkoutOfLinkedWorktree(worktreePath, id) {
+    let body;
+    try {
+        body = await readFile(path.join(worktreePath, ".git"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const match = /^gitdir:\s*(.+)$/m.exec(body.trim());
+    if (!match?.[1])
+        return null;
+    const tail = path.join(".git", "worktrees", id);
+    const gitdir = match[1].trim();
+    if (!gitdir.endsWith(tail))
+        return null;
+    const checkout = gitdir.slice(0, gitdir.length - tail.length).replace(new RegExp(`${path.sep}+$`), "");
+    return checkout === "" ? null : checkout;
+}
+async function directoryCreatedAt(target) {
+    try {
+        return (await stat(target)).mtime.toISOString();
+    }
+    catch {
+        return new Date(0).toISOString();
+    }
+}
+export async function reclaimSession(record, options, env = process.env) {
+    const refused = (reason) => ({
+        sessionId: record.sessionId,
+        removedWorktree: false,
+        deletedBranch: false,
+        droppedRow: false,
+        reason,
+    });
+    if (!isEngineBranch(record.branch))
+        return refused(record.branch === null ? NOT_ISOLATED : FOREIGN_BRANCH);
+    if (record.worktreePath === record.projectPath)
+        return refused(NOT_ISOLATED);
+    if (!insideAnEngineHome(record.worktreePath, env))
+        return refused(FOREIGN_WORKTREE);
+    const facts = await inspectSession(record, env);
+    if (!facts.checkoutPresent)
+        return refused(facts.reason);
+    if (record.status === "open" && !facts.stale) {
+        return refused(`its engine is still running (pid ${String(record.enginePid ?? "unknown")}) — close the session first`);
+    }
+    const force = options.force === true;
+    if (!force && !facts.reclaimable)
+        return refused(facts.reason);
+    const branch = record.branch;
+    const removal = await gitOutcome(force ? ["worktree", "remove", "--force", record.worktreePath] : ["worktree", "remove", record.worktreePath], record.projectPath);
+    await gitOutcome(["worktree", "prune"], record.projectPath);
+    const deletion = await gitOutcome([...(force ? ["branch", "-D"] : ["branch", "-d"]), branch], record.projectPath);
+    const worktreeLeft = await isDirectory(record.worktreePath);
+    const branchLeft = (await gitOutcome(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], record.projectPath)).ok;
+    const cleared = !worktreeLeft && !branchLeft;
+    const droppedRow = cleared && !facts.orphaned
+        ? await updateSessionRegistry(env, (sessions) => sessions.filter((row) => row.sessionId !== record.sessionId)).then(() => true)
+        : false;
+    return {
+        sessionId: record.sessionId,
+        removedWorktree: !worktreeLeft,
+        deletedBranch: !branchLeft,
+        droppedRow,
+        reason: cleared ? null : (deletion.stderr || removal.stderr || "the worktree or the branch could not be removed"),
+    };
+}

package/dist/lib/session-engine/registry.js

@@ -0,0 +1,83 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { sessionsHome } from "./worktree.js";
+export const SESSION_REGISTRY_VERSION = 2;
+export function sessionRegistryPath(env = process.env) {
+    return path.join(sessionsHome(env), "registry.json");
+}
+function asText(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+function asNullableText(value) {
+    return typeof value === "string" ? value : null;
+}
+function narrowRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const row = value;
+    const sessionId = asText(row.sessionId);
+    const projectPath = asText(row.projectPath);
+    const worktreePath = asText(row.worktreePath);
+    const createdAt = asText(row.createdAt);
+    if (!sessionId || !projectPath || !worktreePath || !createdAt)
+        return null;
+    if (row.status !== "open" && row.status !== "closed")
+        return null;
+    if (row.provider !== "claude-code")
+        return null;
+    const enginePid = typeof row.enginePid === "number" && Number.isSafeInteger(row.enginePid) && row.enginePid > 0 ? row.enginePid : null;
+    return {
+        sessionId,
+        projectPath,
+        worktreePath,
+        branch: asNullableText(row.branch),
+        provider: "claude-code",
+        providerSessionId: asNullableText(row.providerSessionId),
+        createdAt,
+        status: row.status,
+        nustack: row.nustack === 0 ? 0 : 1,
+        projectId: asNullableText(row.projectId),
+        permissionMode: asNullableText(row.permissionMode),
+        baseBranch: asNullableText(row.baseBranch),
+        baseCommit: asNullableText(row.baseCommit),
+        enginePid,
+        closedAt: asNullableText(row.closedAt),
+    };
+}
+export async function readSessionRegistry(env = process.env) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(sessionRegistryPath(env), "utf8"));
+    }
+    catch {
+        return { records: [], dropped: 0 };
+    }
+    const rows = parsed?.sessions;
+    if (!Array.isArray(rows))
+        return { records: [], dropped: 0 };
+    const records = [];
+    let dropped = 0;
+    for (const row of rows) {
+        const record = narrowRecord(row);
+        if (record)
+            records.push(record);
+        else
+            dropped += 1;
+    }
+    return { records, dropped };
+}
+let registryWrites = Promise.resolve();
+export function updateSessionRegistry(env, mutate) {
+    const run = async () => {
+        const file = sessionRegistryPath(env);
+        const { records } = await readSessionRegistry(env);
+        const body = JSON.stringify({ v: SESSION_REGISTRY_VERSION, sessions: mutate(records) }, null, 2) + "\n";
+        await mkdir(path.dirname(file), { recursive: true });
+        const temp = `${file}.${process.pid}.tmp`;
+        await writeFile(temp, body, "utf8");
+        await rename(temp, file);
+    };
+    const landed = registryWrites.then(run, run);
+    registryWrites = landed.then(() => undefined, () => undefined);
+    return landed;
+}

package/dist/lib/session-engine/supervisor.js

@@ -1,10 +1,12 @@
 import { execFile } from "node:child_process";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { createInterface } from "node:readline";
 import { ClaudeSession } from "./claudeAdapter.js";
 import { FRAME_VERSION, parseInboundFrame, serializeFrame, } from "./frames.js";
-import { createSessionWorktree, sessionsHome } from "./worktree.js";
+import { inspectSession, reclaimSession } from "./prune.js";
+import { sessionRegistryPath, readSessionRegistry, updateSessionRegistry } from "./registry.js";
+import { createSessionWorktree } from "./worktree.js";
 function defaultProbeClaude(env) {
     return new Promise((resolve) => {
         execFile("claude", ["--version"], { env, timeout: 5_000 }, (error, stdout) => {
@@ -37,9 +39,6 @@ export class SessionSupervisor {
     error(sessionId, code, message) {
         this.emit({ v: FRAME_VERSION, type: "session.error", sessionId, code, message });
     }
-    registryPath() {
-        return path.join(sessionsHome(this.env), "registry.json");
-    }
     async boundProjectOf(projectPath) {
         try {
             const parsed = JSON.parse(await readFile(path.join(projectPath, ".nustack", "workspace.json"), "utf8"));
@@ -61,20 +60,7 @@ export class SessionSupervisor {
         }
     }
     async updateRegistry(mutate) {
-        const run = async () => {
-            const file = this.registryPath();
-            let sessions = [];
-            try {
-                const parsed = JSON.parse(await readFile(file, "utf8"));
-                if (typeof parsed === "object" && parsed !== null && Array.isArray(parsed.sessions)) {
-                    sessions = parsed.sessions;
-                }
-            }
-            catch {
-            }
-            await mkdir(path.dirname(file), { recursive: true });
-            await writeFile(file, JSON.stringify({ v: 2, sessions: mutate(sessions) }, null, 2) + "\n", "utf8");
-        };
+        const run = () => updateSessionRegistry(this.env, mutate);
         this.registryWrites = this.registryWrites.then(run, run);
         return this.registryWrites;
     }
@@ -105,7 +91,7 @@ export class SessionSupervisor {
                 await this.shutdown();
                 return;
             case "session.open":
-                await this.openSession(frame.sessionId, frame.projectPath, frame.permissionMode, frame.isolated, frame.resumeSessionId);
+                await this.openSession(frame.sessionId, frame.projectPath, frame.permissionMode, frame.isolated, frame.resumeSessionId, frame.commit);
                 return;
             case "session.turn": {
                 const session = this.sessions.get(frame.sessionId);
@@ -137,13 +123,24 @@ export class SessionSupervisor {
                 session.adapter.stop();
                 return;
             }
+            case "session.list":
+                await this.sendRoster();
+                return;
+            case "session.reclaim":
+                await this.reclaimRow(frame.sessionId);
+                return;
         }
     }
-    async openSession(sessionId, projectPath, permissionMode, isolated, resumeSessionId) {
+    async openSession(sessionId, projectPath, permissionMode, isolated, resumeSessionId, commit) {
         if (this.sessions.has(sessionId))
             return this.error(sessionId, "SESSION_ALREADY_OPEN", `session ${sessionId} is already open`);
         this.status(sessionId, "starting");
-        const worktree = await createSessionWorktree(projectPath, sessionId, this.env, isolated === true);
+        const worktree = await createSessionWorktree(projectPath, sessionId, this.env, isolated === true, commit);
+        if (worktree.commitRefusal !== null) {
+            this.error(sessionId, worktree.commitRefusal.code, worktree.commitRefusal.detail);
+            this.status(sessionId, "error", `could not open ${String(commit)}`);
+            return;
+        }
         const record = {
             sessionId,
             projectPath,
@@ -155,6 +152,11 @@ export class SessionSupervisor {
             status: "open",
             nustack: 1,
             projectId: await this.boundProjectOf(projectPath),
+            permissionMode: permissionMode ?? null,
+            baseBranch: worktree.baseBranch,
+            baseCommit: worktree.baseCommit,
+            enginePid: process.pid,
+            closedAt: null,
         };
         const adapterOptions = {
             cwd: worktree.worktreePath,
@@ -194,7 +196,7 @@ export class SessionSupervisor {
                 if (!wasExpected)
                     this.error(sessionId, "ADAPTER_FAILED", `claude exited unexpectedly (code ${String(code)})`);
                 this.emit({ v: FRAME_VERSION, type: "session.closed", sessionId });
-                void this.updateRegistry((sessions) => sessions.map((row) => (row.sessionId === sessionId ? { ...row, status: "closed" } : row)));
+                void this.updateRegistry((sessions) => sessions.map((row) => row.sessionId === sessionId ? { ...row, status: "closed", closedAt: new Date().toISOString() } : row));
                 void this.moveSessionRow(record, wasExpected ? "done" : "failed");
             },
         };
@@ -232,16 +234,87 @@ export class SessionSupervisor {
             worktreePath: worktree.worktreePath,
             branch: worktree.branch,
             isolated: worktree.isolated,
+            commit: worktree.baseCommit,
         });
         this.status(sessionId, "ready");
     }
+    async sendRoster() {
+        const { records, dropped } = await readSessionRegistry(this.env);
+        const rows = [];
+        for (const record of records) {
+            const attached = this.sessions.has(record.sessionId);
+            const facts = await inspectSession(record, this.env);
+            const reclaimable = !attached && facts.reclaimable;
+            const reason = attached ? "this engine is running it — close the session first" : facts.reason;
+            rows.push({
+                sessionId: record.sessionId,
+                projectPath: record.projectPath,
+                worktreePath: record.worktreePath,
+                branch: record.branch,
+                createdAt: record.createdAt,
+                status: record.status,
+                closedAt: record.closedAt ?? null,
+                permissionMode: record.permissionMode ?? null,
+                baseBranch: record.baseBranch ?? null,
+                attached,
+                liveElsewhere: !attached && record.status === "open" && typeof record.enginePid === "number" && !facts.stale,
+                isolated: facts.isolated,
+                checkoutPresent: facts.checkoutPresent,
+                worktreePresent: facts.worktreePresent,
+                branchExists: facts.branchExists,
+                reading: facts.reading,
+                dirty: facts.dirty,
+                stale: facts.stale,
+                reclaimable,
+                reason,
+            });
+        }
+        this.emit({
+            v: FRAME_VERSION,
+            type: "session.roster",
+            registryPath: sessionRegistryPath(this.env),
+            unreadable: dropped,
+            sessions: rows,
+        });
+    }
+    async reclaimRow(sessionId) {
+        if (this.sessions.has(sessionId)) {
+            return this.error(sessionId, "SESSION_ATTACHED", `session ${sessionId} is open in this engine — close it first`);
+        }
+        const { records } = await readSessionRegistry(this.env);
+        const record = records.find((row) => row.sessionId === sessionId);
+        if (!record)
+            return this.error(sessionId, "SESSION_UNKNOWN", `no session ${sessionId} in this machine's registry`);
+        const reclaim = this.registryWrites.then(() => reclaimSession(record, {}, this.env), () => reclaimSession(record, {}, this.env));
+        this.registryWrites = reclaim.then(() => undefined, () => undefined);
+        try {
+            const outcome = await reclaim;
+            this.emit({
+                v: FRAME_VERSION,
+                type: "session.reclaimed",
+                sessionId,
+                removedWorktree: outcome.removedWorktree,
+                deletedBranch: outcome.deletedBranch,
+                droppedRow: outcome.droppedRow,
+                reason: outcome.reason,
+            });
+        }
+        catch (error) {
+            this.error(sessionId, "RECLAIM_FAILED", error instanceof Error ? error.message : String(error));
+        }
+    }
     async shutdown() {
         if (this.shuttingDown)
             return;
         this.shuttingDown = true;
+        const held = [...this.sessions.keys()];
         for (const [, session] of this.sessions)
             session.adapter.stop();
         this.sessions.clear();
+        if (held.length > 0) {
+            const closedAt = new Date().toISOString();
+            await this.updateRegistry((sessions) => sessions.map((row) => (held.includes(row.sessionId) && row.status === "open" ? { ...row, status: "closed", closedAt } : row)));
+        }
         this.lines?.close();
         this.resolveDone?.();
     }

package/dist/lib/session-engine/worktree.js

@@ -9,25 +9,81 @@ export function sessionsHome(env = process.env) {
         return override;
     return path.join(os.homedir(), ".nustack", "sessions");
 }
+export const LEGACY_ENGINE_BRANCH_PREFIX = "nustack/lane-";
+const FETCH_TIMEOUT_MS = 10 * 60_000;
+export function legacyEngineHome(env = process.env) {
+    const override = env.NUSTACK_LEGACY_ENGINE_HOME;
+    if (override && override !== "")
+        return override;
+    return path.join(os.homedir(), ".nustack", "lanes");
+}
 function git(args, cwd) {
+    return gitOutcome(args, cwd).then((outcome) => (outcome.ok ? outcome.stdout : null));
+}
+export function gitOutcome(args, cwd, timeoutMs = 15_000) {
     return new Promise((resolve) => {
-        execFile("git", args, { cwd, timeout: 15_000 }, (error, stdout) => {
-            resolve(error ? null : stdout.trim());
-        });
+        const failed = (error) => {
+            resolve({ ok: false, code: null, stdout: "", stderr: error instanceof Error ? error.message : String(error) });
+        };
+        try {
+            execFile("git", args, { cwd, timeout: timeoutMs }, (error, stdout, stderr) => {
+                const raw = error?.code;
+                const code = error ? (typeof raw === "number" ? raw : null) : 0;
+                resolve({ ok: !error, code, stdout: stdout.trim(), stderr: stderr.trim() });
+            });
+        }
+        catch (error) {
+            failed(error);
+        }
     });
 }
-export async function createSessionWorktree(projectPath, sessionId, env = process.env, isolate = false) {
-    const inPlace = { worktreePath: projectPath, branch: null, isolated: false };
-    if (!isolate)
+export async function createSessionWorktree(projectPath, sessionId, env = process.env, isolate = false, commit) {
+    const inPlace = {
+        worktreePath: projectPath,
+        branch: null,
+        isolated: false,
+        baseBranch: null,
+        baseCommit: null,
+        commitRefusal: null,
+    };
+    if (!isolate && commit === undefined)
         return inPlace;
     const isRepo = await git(["rev-parse", "--is-inside-work-tree"], projectPath);
-    if (isRepo !== "true")
-        return inPlace;
+    if (isRepo !== "true") {
+        return commit === undefined
+            ? inPlace
+            : { ...inPlace, commitRefusal: { code: "COMMIT_UNREACHABLE", detail: `${projectPath} is not a git checkout, so ${commit} cannot be opened here.` } };
+    }
+    if (commit !== undefined) {
+        const refusal = await fetchCommit(projectPath, commit);
+        if (refusal !== null)
+            return { ...inPlace, commitRefusal: refusal };
+    }
+    const head = await git(["rev-parse", "--abbrev-ref", "HEAD"], projectPath);
+    const baseBranch = head === null || head === "HEAD" ? null : head;
     const branch = `${ENGINE_SESSION_BRANCH_PREFIX}${sessionId}`;
     const worktreePath = path.join(sessionsHome(env), "worktrees", sessionId);
     await mkdir(path.dirname(worktreePath), { recursive: true });
-    const added = await git(["worktree", "add", worktreePath, "-b", branch], projectPath);
-    if (added === null)
-        return inPlace;
-    return { worktreePath, branch, isolated: true };
+    const added = await git(commit === undefined
+        ? ["worktree", "add", worktreePath, "-b", branch]
+        : ["worktree", "add", worktreePath, "-b", branch, commit], projectPath);
+    if (added === null) {
+        return commit === undefined
+            ? inPlace
+            : { ...inPlace, commitRefusal: { code: "COMMIT_UNREACHABLE", detail: `git refused a worktree for ${commit} in ${projectPath}.` } };
+    }
+    const baseCommit = await git(["rev-parse", "HEAD"], worktreePath);
+    return { worktreePath, branch, isolated: true, baseBranch, baseCommit, commitRefusal: null };
+}
+async function fetchCommit(projectPath, commit) {
+    const has = () => gitOutcome(["cat-file", "-e", `${commit}^{commit}`], projectPath);
+    if ((await has()).ok)
+        return null;
+    let fetched = await gitOutcome(["fetch", "origin", commit], projectPath, FETCH_TIMEOUT_MS);
+    if (!fetched.ok)
+        fetched = await gitOutcome(["fetch", "origin"], projectPath, FETCH_TIMEOUT_MS);
+    if ((await has()).ok)
+        return null;
+    const said = `${fetched.stderr}\n${fetched.stdout}`.trim();
+    return { code: "COMMIT_UNREACHABLE", detail: said === "" ? `${commit} is not in this checkout and origin did not have it.` : said };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.10.0-dev.19",
+  "version": "0.10.0-dev.21",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -34,8 +34,8 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/nustack.ui": "0.0.0",
-    "@nurix/nustack.studio": "0.0.0"
+    "@nurix/nustack.studio": "0.0.0",
+    "@nurix/nustack.ui": "0.0.0"
   },
   "publishConfig": {
     "access": "public"