@zq-silk/yui 0.11.2 → 0.12.0

package/dist/interaction/operatorPresentation.js

@@ -1,96 +1,40 @@
-import { formatTimestamp } from "../output/timePresentation.js";
-import { formatInputRequestReceiptId, formatTaskRecordReference } from "../task/taskRecordReference.js";
-export function createInputRequestOperatorPresentation(request, context) {
-    const policy = request.policy;
-    const recommendation = policy.kind === "recommended"
-        ? request.choices.find(({ key }) => key === policy.recommendedChoiceKey)
-        : undefined;
-    if (policy.kind === "recommended" && recommendation === undefined) {
-        throw new Error(`Input request ${request.id} recommendation ${policy.recommendedChoiceKey} is missing.`);
-    }
-    return {
-        category: "attention",
-        taskId: request.taskId,
-        receiptId: formatInputRequestReceiptId(request.taskId, request.id),
-        source: { kind: "input-request", taskId: request.taskId, localId: request.id },
-        text: [
-            "A Task Leader is waiting for a boundary decision. Inspect it before involving the user.",
-            "Present it only when it is a user-owned choice, authorization, credential, unavailable external fact, or irreversible operation.",
-            `If it is an implementation, scheduling, review, or recoverable runtime choice, do not present it to the user; return it to the Leader with: yui task input cancel ${request.taskId} ${request.id} --reason \"Operator returned: not a user-owned boundary\"`,
-            "For a user-owned boundary, do not answer it yourself; do not answer or choose on the user's behalf; relay the user's exact response only.",
-            `Task: ${request.taskId}`,
-            `Input: ${request.id}`,
-            `Question: ${request.question}`,
-            ...(request.choices.length === 0
-                ? ["Answer type: free text"]
-                : ["Choices:", ...request.choices.map(({ key, label }) => `  ${key}: ${label}`)]),
-            ...(policy.kind === "required"
-                ? ["Decision policy: this requires the user's response; there is no automatic fallback."]
-                : [
-                    `Agent recommendation: ${recommendation.key}: ${recommendation.label}`,
-                    `Automatic fallback after: ${formatTimestamp(policy.timeoutAt, context.timeZone)}`
-                ]),
-            `Inspect: yui task input show ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")}`,
-            request.choices.length === 0
-                ? `After the user replies: yui task input answer ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")} --text "<answer>"`
-                : `After the user chooses: yui task input answer ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")} --choice <key>`
-        ].join("\n")
-    };
-}
-export function createLeaderRecoveryOperatorPresentation(notification) {
+/**
+ * One mailbox batch becomes one short synthetic user message. The durable
+ * records remain the context authority; this wake text carries only stable
+ * identities and exact CLI reads, never copied Task or Provider narrative.
+ */
+export function createOperatorBatchPresentation(batchId, items) {
+    if (items.length === 0)
+        throw new Error("Operator presentation requires at least one item.");
     return {
-        category: "attention",
-        taskId: notification.taskId,
-        receiptId: `leader-recovery:${notification.taskId}:${notification.createdAt}`,
-        source: { kind: "leader-recovery", id: notification.taskId },
+        receiptId: `operator-batch:${batchId}`,
         text: [
-            "A Task cannot recover its Leader automatically and needs user attention.",
-            `Task: ${notification.taskId}`,
-            `Failure: ${notification.message}`,
-            `Inspect: yui task show ${notification.taskId}`,
-            "Recovery status: yui jobs list",
-            `Retry after inspection: yui jobs retry leader-recovery:${notification.taskId}`
+            "[Yui updates]",
+            "Yui recorded the following durable updates. Inspect the referenced records and present only information that changes the user's understanding, authorization, or next action.",
+            ...items.flatMap(renderItem)
         ].join("\n")
     };
 }
-export function createLeaderStallOperatorPresentation(notification) {
-    return {
-        category: "attention",
-        taskId: notification.taskId,
-        receiptId: `leader-stall:${notification.taskId}:${notification.runId}:${notification.progressAt}`,
-        source: {
-            kind: "leader-stall",
-            id: `${notification.runId}:${notification.progressAt}`
-        },
-        text: [
-            "A Task Leader is truly stalled and needs user attention.",
-            `Task: ${notification.taskId}`,
-            `Leader Run: ${notification.runId}`,
-            `lastProgressAt: ${notification.progressAt}`,
-            "Classification: truly-stalled",
-            `Evidence: ${notification.evidenceKey}`,
-            "Controller preserved the exact Run/Session fence and performed no automatic Enter, reset, retry, kill, or Session replacement.",
-            `Inspect: yui task context ${notification.taskId}`,
-            "Choose the supported continuation, reset, retry, Agent change, or user-input action only after inspection."
-        ].join("\n")
-    };
+function renderItem(item) {
+    if (item.kind === "input-request") {
+        const { request } = item;
+        return [
+            `- User input requested: ${request.taskId}/${request.id}`,
+            `  Inspect: yui task input show ${request.taskId}/${request.id}`
+        ];
+    }
+    const { event } = item;
+    return [
+        `- ${eventLabel(event)}: ${event.taskId}/${event.id}`,
+        `  Inspect: yui task event show ${event.taskId} ${event.id}`
+    ];
 }
-export function createTaskTerminalOperatorPresentation(notification) {
-    const action = notification.status === "completed" ? "completed" : "retired";
-    const actor = notification.by === "leader"
-        ? "its Leader"
-        : notification.by === "operator"
-            ? "the Operator"
-            : "the user";
-    return {
-        category: "information",
-        taskId: notification.taskId,
-        receiptId: `task-terminal:${notification.taskId}:${notification.status}:${notification.createdAt}`,
-        source: { kind: "task-terminal", id: notification.taskId },
-        text: [
-            `Task ${notification.taskId} was ${action} by ${actor}.`,
-            `Summary: ${notification.summary}`,
-            `Inspect: yui task show ${notification.taskId}`
-        ].join("\n")
-    };
+function eventLabel(event) {
+    switch (event.type) {
+        case "task.completed": return "Task completed";
+        case "task.retired": return "Task retired";
+        case "leader.attention-required": return "Task Leader needs attention";
+        case "run.stalled": return "Task Leader stalled";
+        default: return `Task event ${event.type}`;
+    }
 }

package/dist/lifecycle/exactRunTerminalization.js

@@ -12,7 +12,7 @@ import { createYieldReceipt } from "../run/yieldReceipt.js";
 import { recordExecutionLaneResult } from "../execution/executionGroup.js";
 import { isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { runOwnsBlockingProviderContinuation } from "../runtime/runtimeContinuationProjection.js";
-import { clearMatchingLeaderStallAttention, latestRunDurableProgressAt, RUN_RECOVERY_APPLIED_EVENT, RUN_RECOVERY_REQUESTED_EVENT } from "../scheduler/roleRunStall.js";
+import { latestRunDurableProgressAt, RUN_RECOVERY_APPLIED_EVENT, RUN_RECOVERY_REQUESTED_EVENT } from "../scheduler/roleRunStall.js";
 import { markTaskWakeConsumed } from "../scheduler/taskWake.js";
 import { workItemExecutionGroupById, workItemOwnsUnresolvedExecutionLane, updateWorkItemExecutionGroup, updateWorkItemStatus } from "../workItem/workItem.js";
 /**
@@ -496,7 +496,6 @@ function recoverExactAgentRunInTransaction(store, input) {
         }
     }
     store.saveEvent(input.taskId, createTaskEvent(store.nextEventId(input.taskId), input.taskId, RUN_RECOVERY_APPLIED_EVENT, { ...eventPayload, status: "terminated" }, input.now));
-    clearMatchingLeaderStallAttention(store, input.taskId, input.runId);
     if (input.roleName !== "leader") {
         enqueueWork(store, { kind: "role", taskId: input.taskId, roleName: "leader" }, "run-recovery-terminated", input.now, [{ type: "run", taskId: input.taskId, id: input.runId }]);
     }

package/dist/lifecycle/taskRoleSessionReset.js

@@ -3,7 +3,7 @@ import { resetTaskRoleSession } from "../executor/agentExecutor.js";
 import { createTaskEvent } from "../event/taskEvent.js";
 import { createTaskMessage } from "../message/message.js";
 import { updateRoleStatus } from "../role/role.js";
-import { createLeaderRecoveryNotification } from "../scheduler/operatorNotification.js";
+import { enqueueOperatorEvent } from "../scheduler/operatorEvent.js";
 import { recordLeaderFailure } from "../scheduler/leaderFailure.js";
 import { RUNTIME_CLEANUP_REQUIRED_REASON, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
@@ -70,27 +70,19 @@ export function resetTaskRoleSessionGeneration(store, taskId, roleName, reason,
         ...(activeRun.workItemId === undefined ? {} : { workItemId: activeRun.workItemId })
     });
     store.saveMessage(task.id, message);
-    store.saveEvent(task.id, createTaskEvent(store.nextEventId(task.id), task.id, "runtime.role-session-reset", {
+    const resetEvent = createTaskEvent(store.nextEventId(task.id), task.id, "runtime.role-session-reset", {
         roleName: role.name,
         reason: summary,
         ...(activeRun === null ? {} : { runId: activeRun.id }),
         ...(current?.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: current.nativeSessionId })
-    }, now));
+    }, now);
+    store.saveEvent(task.id, resetEvent);
     if (role.name === "leader") {
         const nativeSessionId = current?.nativeSessionId ?? `reset-${task.id}`;
         store.saveLeaderFailure(recordLeaderFailure(task.id, nativeSessionId, summary, now, store.getLeaderFailure(task.id)));
-        store.saveOperatorNotification(createLeaderRecoveryNotification(task.id, summary, now, store.getOperatorNotification(task.id)));
-        enqueueWork(store, { kind: "operator" }, "leader-run-failed", now, [
-            { type: "task", id: task.id },
-            { type: "message", taskId: task.id, id: message.id },
-            ...(activeRun === null ? [] : [{
-                    type: "run",
-                    taskId: task.id,
-                    id: activeRun.id
-                }])
-        ]);
+        enqueueOperatorEvent(store, resetEvent, "leader-run-failed", now);
     }
     else {
         enqueueWork(store, { kind: "role", taskId: task.id, roleName: "leader" }, "role-run-failed", now, [

package/dist/observability/orchestrationMetrics.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import { classifyReviewRoundOutcome } from "../review/reviewOutcomeClassifier.js";
 import { projectFirstProgressAdvisory } from "../runtime/firstProgressAdvisory.js";
 /** One Task's orchestration cost and advisory projection, with no writes. */
@@ -129,10 +130,14 @@ function projectAdvisories(facts, classifications, fullRounds, repeatedIdentitie
     const recent = semanticFull.slice(-3);
     const recentIds = new Set(recent.map(({ id }) => id));
     const newFinding = facts.reviewFindings.some(({ firstReviewRoundId }) => recentIds.has(firstReviewRoundId));
-    if (semanticFull.length > 2 && !newFinding) {
+    const sameCandidate = recent.length === 3
+        && recent.every((round) => isDeepStrictEqual(round.taskCandidate, recent[0].taskCandidate));
+    const sameReviewer = recent.length === 3
+        && recent.every((round) => round.reviewerRoleName === recent[0].reviewerRoleName);
+    if (sameCandidate && sameReviewer && !newFinding) {
         result.push({
-            code: "review-budget-exhausted",
-            reason: `${semanticFull.length} full semantic Reviews ran and the latest three produced no new finding; stop repeating full rounds without a changed head or new risk.`,
+            code: "repeated-full-review",
+            reason: `The same Reviewer completed three full semantic Reviews of the same frozen candidate without a new finding; this is a cost advisory, not a Review limit.`,
             refs: recent.map(({ id }) => `review-round:${id}`)
         });
     }

package/dist/profile/agentProfile.js

@@ -75,7 +75,7 @@ export function builtinAgentProfileInputs() {
         {
             id: "reviewer",
             description: "Review one candidate against the user's core outcome, supported behavior, and direct evidence.",
-            instructions: "Start from user intent and acceptance criteria. Inspect the complete relevant change and report only reachable, material, actionable problems with direct evidence. Separate defects from verification gaps, and prefer the smallest sufficient correction. Follow the bound Project's Policy and Knowledge for build, test, migration, release, and review expectations; do not import rules from another Project or Task. For normal software delivery, review the frozen Task result as one final ReviewRound rather than inventing a per-WorkItem protocol unless the Project Policy explicitly requires one. A Task-final Round has no synthetic WorkItem anchor, and a compatible Reviewer Session may continue across changed-head Rounds without reusing an earlier verdict. Do not turn speculative or extreme edge cases into new state, retries, fallbacks, or protocol. In a ReviewRound-owned workspace you may edit source or tests, run local checks, and optionally commit diagnostic evidence. Never push, integrate, mutate Task state, touch another workspace or stable checkout, or write the real Yui control-plane home. Report complete findings, checks actually run, uncertainty, and bounded next actions through the exact Review yield; Yui preserves the full free-form report. Expose evidence and options to the Leader, who decides.",
+            instructions: "Start from user intent and acceptance criteria. Inspect the complete relevant change and report only reachable, material, actionable problems with direct evidence. Separate defects from verification gaps, and prefer the smallest sufficient correction. Follow the bound Project's Policy and Knowledge for build, test, migration, release, and review expectations; do not import rules from another Project or Task. For normal software delivery, review the frozen Task result as one final ReviewRound rather than inventing a per-WorkItem protocol unless the Project Policy explicitly requires one. A Task-final Round has no synthetic WorkItem anchor, and the Reviewer Session and physical workspace continue across changed-head Rounds without reusing an earlier verdict. The current Run's frozen candidate remains the only scope even if Task main advances. For Delta Recheck, return equivalent-and-accepted, finding, or requires-full-review with explicit reasoning; never create the next Round. Do not turn speculative or extreme edge cases into new state, retries, fallbacks, or protocol. In the Review workspace you may edit source or tests, run local checks, and optionally commit diagnostic evidence. Never push, integrate, mutate Task state, touch another workspace or stable checkout, or write the real Yui control-plane home. Report complete findings, checks actually run, uncertainty, and bounded next actions through the exact Review yield; Yui preserves the full free-form report. Expose evidence and options to the Leader, who decides.",
             defaultAccess: "write"
         }
     ];

package/dist/release/cliHomeReleaseFence.js

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { UNSUPPORTED, collectRuntimeBuildIdentity, createProductionRuntimeIdentityPorts } from "../observability/runtimeIdentity.js";
+import { readCompatibleHomeIdentity } from "../storage/compatibleTaskStore.js";
+import { detectRunningRelease, readActiveReleasePointer, releaseDirectoryName } from "./runtimeRelease.js";
+/**
+ * Prevent a checkout or otherwise unverified CLI from entering a Home that is
+ * already owned by an immutable active release. This fence runs before any
+ * TaskStore is opened, so even schema discovery cannot advance SQLite state.
+ * Published global packages remain the stable ordinary CLI boundary; an exact
+ * installed release may also run when it is active or is the explicit handover
+ * target.
+ */
+export function assertCliHomeReleaseFence(input) {
+    const active = readActiveReleasePointer(input.home);
+    if (active === null)
+        return "unregistered-home";
+    const running = detectRunningRelease(input.entryPath);
+    if (running !== null) {
+        if (matchesActiveRelease(running.manifest, active))
+            return "active-release";
+        if (isExplicitActivation(input.args, running.manifest))
+            return "release-activation";
+        throw fenceError(input, active, "installed-release", running.manifest);
+    }
+    const build = collectRuntimeBuildIdentity(createProductionRuntimeIdentityPorts(input.packageRoot, input.entryPath));
+    const distribution = readPackageDistribution(input.packageRoot);
+    if (distribution === "published" && build.sourceCommit === UNSUPPORTED) {
+        return "published-package";
+    }
+    const source = distribution === "checkout" || build.sourceCommit !== UNSUPPORTED
+        ? "checkout-local"
+        : "unverified-local";
+    throw fenceError(input, active, source, undefined, build);
+}
+/** Render bounded, non-secret identity evidence for a migration diagnosis. */
+export function describeCliHomeInvocation(input) {
+    const running = detectRunningRelease(input.entryPath);
+    const collected = collectRuntimeBuildIdentity(createProductionRuntimeIdentityPorts(input.packageRoot, input.entryPath));
+    const distribution = readPackageDistribution(input.packageRoot);
+    const source = running !== null
+        ? "installed-release"
+        : distribution === "published" && collected.sourceCommit === UNSUPPORTED
+            ? "published-package"
+            : distribution === "checkout" || collected.sourceCommit !== UNSUPPORTED
+                ? "checkout-local"
+                : "unverified-local";
+    let homeId = "unknown";
+    try {
+        homeId = readCompatibleHomeIdentity(input.home).homeId;
+    }
+    catch {
+        // The primary migration error remains authoritative when identity is unreadable.
+    }
+    let activeRelease = "none";
+    let activeBuild = "none";
+    try {
+        const active = readActiveReleasePointer(input.home);
+        if (active !== null) {
+            activeRelease = active.releaseId;
+            activeBuild = active.buildId;
+        }
+    }
+    catch {
+        activeRelease = "unreadable";
+        activeBuild = "unreadable";
+    }
+    const version = running?.manifest.version ?? collected.packageVersion;
+    const buildId = running?.manifest.buildId
+        ?? (source === "checkout-local" ? "checkout" : source);
+    const sourceCommit = running?.manifest.sourceCommit ?? (collected.sourceCommit === UNSUPPORTED ? "unknown" : collected.sourceCommit);
+    return [
+        `CLI: version=${diagnostic(version)} build=${diagnostic(buildId)} sourceCommit=${diagnostic(sourceCommit)}`,
+        `Home: homeId=${diagnostic(homeId)} activeRelease=${diagnostic(activeRelease)} activeBuild=${diagnostic(activeBuild)}`,
+        `Invocation: source=${source}`
+    ].join("\n");
+}
+function matchesActiveRelease(manifest, active) {
+    return active.releaseId === releaseDirectoryName(manifest)
+        && active.version === manifest.version
+        && active.buildId === manifest.buildId
+        && active.packageDigest === manifest.packageDigest;
+}
+function isExplicitActivation(args, manifest) {
+    if (args.length !== 3 || args[0] !== "release" || args[1] !== "activate")
+        return false;
+    return args[2] === releaseDirectoryName(manifest) || args[2] === manifest.buildId;
+}
+function readPackageDistribution(packageRoot) {
+    try {
+        const value = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        if (value.private === true)
+            return "checkout";
+        if (value.private === false)
+            return "published";
+    }
+    catch {
+        // A missing or damaged package identity is not publication evidence.
+    }
+    return "unknown";
+}
+function fenceError(input, active, source, release, collected = collectRuntimeBuildIdentity(createProductionRuntimeIdentityPorts(input.packageRoot, input.entryPath))) {
+    let homeId = "unknown";
+    try {
+        homeId = readCompatibleHomeIdentity(input.home).homeId;
+    }
+    catch {
+        // The release fence must still diagnose and reject an unreadable Home.
+    }
+    const version = release?.version ?? collected.packageVersion;
+    const buildId = release?.buildId ?? (source === "checkout-local" ? "checkout" : "unknown");
+    const sourceCommit = release?.sourceCommit ?? (collected.sourceCommit === UNSUPPORTED ? "unknown" : collected.sourceCommit);
+    return new Error([
+        `Refusing ${source} CLI access to a Home owned by another active release.`,
+        `CLI: version=${diagnostic(version)} build=${diagnostic(buildId)} sourceCommit=${diagnostic(sourceCommit)}`,
+        `Home: homeId=${diagnostic(homeId)} activeRelease=${diagnostic(active.releaseId)} activeBuild=${diagnostic(active.buildId)}`,
+        `Invocation: source=${source}`,
+        "Use the published global yui for this Home, or run make install-local without overriding its isolated YUI_HOME."
+    ].join("\n"));
+}
+function diagnostic(value) {
+    return value.replace(/[^A-Za-z0-9._:+/@-]/gu, "?").slice(0, 160);
+}

package/dist/repository/checkoutSwap.js

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { rename as defaultRename, rm as defaultRm } from "node:fs/promises";
+const realPorts = {
+    rename: (sourcePath, targetPath) => defaultRename(sourcePath, targetPath),
+    remove: (path) => defaultRm(path, { recursive: true, force: true })
+};
+/**
+ * Heal the on-disk state of a crashed earlier swap before any new destructive
+ * step runs. A backup next to a live checkout is a leftover from a completed
+ * swap whose cleanup crashed and is removed; a backup without a live checkout
+ * means the crash happened mid-swap, so the previous checkout is restored
+ * intact. With no backup there is nothing to heal.
+ */
+export async function healCheckoutSwap(request, ports = realPorts) {
+    if (!existsSync(request.backupPath))
+        return;
+    if (existsSync(request.currentPath)) {
+        await ports.remove(request.backupPath);
+        return;
+    }
+    await ports.rename(request.backupPath, request.currentPath);
+}
+/**
+ * Promote a prepared staging checkout into the registered path without ever
+ * leaving the registered path without a valid repository. The previous
+ * checkout is moved to the backup path first; if the promotion fails it is
+ * restored and the staging clone is removed. A crash between the two renames
+ * is healed by {@link healCheckoutSwap} on the next run.
+ */
+export async function swapManagedCheckout(request, ports = realPorts) {
+    await healCheckoutSwap(request, ports);
+    await ports.rename(request.currentPath, request.backupPath);
+    try {
+        await ports.rename(request.stagingPath, request.currentPath);
+    }
+    catch (error) {
+        try {
+            await ports.rename(request.backupPath, request.currentPath);
+        }
+        catch (rollbackError) {
+            throw new Error(`Checkout swap failed and rollback was incomplete: ${messageOf(error)}; `
+                + `rollback failed: ${messageOf(rollbackError)}. `
+                + `The previous checkout remains parked at ${request.backupPath}.`);
+        }
+        await ports.remove(request.stagingPath).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Restore the parked previous checkout after a committed swap had to be undone
+ * (for example because the catalog transaction refused the change). The
+ * promoted clone is discarded first; if the restore fails the parked checkout
+ * stays recoverable through {@link healCheckoutSwap}.
+ */
+export async function restoreCheckoutSwap(request, ports = realPorts) {
+    await ports.remove(request.currentPath);
+    await ports.rename(request.backupPath, request.currentPath);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/repository/gitWorkspace.js

@@ -694,6 +694,42 @@ export class NodeGitWorkspace {
             throw new Error(`Git reset compensation failed for ${target}; Candidate materialization remains retained for diagnosis.`, { cause: error });
         }
     }
+    async resetToCommit(input) {
+        const root = await canonicalDirectory(input.repositoryPath, "Project");
+        const expectedHead = requireText(input.expectedHead, "Expected head");
+        const targetCommit = requireText(input.targetCommit, "Target commit");
+        if (!await this.isClean(root)) {
+            throw new Error(`Project checkout must be clean before reset: ${root}.`);
+        }
+        const currentHead = (await this.inspect(root, "HEAD")).baseCommit;
+        if (currentHead.toLowerCase() !== expectedHead.toLowerCase()) {
+            throw new Error(`Project checkout changed before reset: ${root} (${currentHead}).`);
+        }
+        // Verify the target commit resolves before moving the branch.
+        await gitLine(["-C", root, "rev-parse", "--verify", "--end-of-options", `${targetCommit}^{commit}`]);
+        await git(["-C", root, "reset", "--hard", targetCommit]);
+        const restoredHead = (await this.inspect(root, "HEAD")).baseCommit;
+        if (restoredHead.toLowerCase() !== targetCommit.toLowerCase() || !await this.isClean(root)) {
+            throw new Error(`Project checkout did not reset to the exact target commit: ${root}.`);
+        }
+    }
+    async listWorktrees(repositoryPath) {
+        const root = await canonicalDirectory(repositoryPath, "Project");
+        const output = await git(["-C", root, "worktree", "list", "--porcelain"]);
+        return output
+            .split(/\r?\n/u)
+            .filter((line) => line.startsWith("worktree "))
+            .map((line) => line.slice("worktree ".length).trim());
+    }
+    async listCommitsBetween(input) {
+        const root = await canonicalDirectory(input.repositoryPath, "Project");
+        const range = `${requireText(input.baseCommit, "Base commit")}..${requireText(input.headCommit, "Head commit")}`;
+        const output = await git(["-C", root, "log", "--oneline", range]);
+        return output
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
     async #assertRefreshCheckout(repositoryPath, stableRef, expectedCommit) {
         if (stableRef !== "HEAD") {
             const currentBranch = await this.headRef(repositoryPath);

package/dist/repository/project.js

@@ -8,7 +8,7 @@ export function managedProjectPath(home, projectId) {
 export function createProject(id, name, path, branches, now, metadata = {}) {
     const timestamp = now.toISOString();
     return validateProject({
-        schemaVersion: 4,
+        schemaVersion: 5,
         id: requireIdentity(id, "Project id"),
         name: validateProjectName(name),
         aliases: normalizeAliases(metadata.aliases ?? [], name),
@@ -19,6 +19,7 @@ export function createProject(id, name, path, branches, now, metadata = {}) {
             : { remoteUrl: requireText(metadata.remoteUrl, "Project remote URL") }),
         stableBranch: requireGitRef(branches.stable, "Project stable branch"),
         developmentBranch: requireGitRef(branches.development, "Project development branch"),
+        status: "active",
         knowledge: [],
         knowledgeProposals: [],
         createdAt: timestamp,
@@ -28,6 +29,38 @@ export function createProject(id, name, path, branches, now, metadata = {}) {
 export function validateProjectName(value) {
     return requireIdentity(value, "Project name");
 }
+/**
+ * Soft-retire a Project: mark it retired and record the audit trail. The
+ * catalog record, checkout, and every historical Task/Run/Review/Integration/
+ * Publication reference are retained. Retiring an already-retired Project
+ * fails closed; a retired Project must be deleted (or kept) as-is.
+ */
+export function retireProject(project, reason, by, now) {
+    if (project.status === "retired") {
+        throw new Error(`Project is already retired: ${project.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateProject({
+        ...project,
+        status: "retired",
+        retirement: {
+            reason: requireText(reason, "Project retirement reason"),
+            retiredBy: by,
+            retiredAt: timestamp
+        },
+        updatedAt: timestamp
+    });
+}
+/**
+ * Refuse a mutation or new binding against a retired Project. Read-only
+ * inspection (`project show`, `project diagnose`, knowledge reads) remains
+ * allowed, so historical evidence stays auditable.
+ */
+export function assertProjectActive(project, action) {
+    if (project.status === "retired") {
+        throw new Error(`Project is retired and cannot ${action}: ${project.id}.`);
+    }
+}
 export function addProjectKnowledge(project, id, title, body, now, provenance) {
     const timestamp = now.toISOString();
     const knowledge = {
@@ -243,8 +276,8 @@ export function assertProjectCatalog(projects) {
     }
 }
 export function validateProject(project) {
-    if (project.schemaVersion !== 4) {
-        throw new Error("Project must use schemaVersion 4.");
+    if (project.schemaVersion !== 5) {
+        throw new Error("Project must use schemaVersion 5.");
     }
     requireIdentity(project.id, "Project id");
     requireIdentity(project.name, "Project name");
@@ -252,6 +285,23 @@ export function validateProject(project) {
     if (project.ownership !== "managed" && project.ownership !== "external") {
         throw new Error(`Project ownership is invalid: ${String(project.ownership)}.`);
     }
+    if (project.status !== "active" && project.status !== "retired") {
+        throw new Error(`Project status is invalid: ${String(project.status)}.`);
+    }
+    if (project.status === "retired") {
+        const retirement = project.retirement;
+        if (retirement === undefined) {
+            throw new Error(`Retired Project must carry its retirement record: ${project.id}.`);
+        }
+        requireText(retirement.reason, "Project retirement reason");
+        if (retirement.retiredBy !== "user" && retirement.retiredBy !== "operator") {
+            throw new Error("Project retirement actor is invalid.");
+        }
+        requireTimestamp(retirement.retiredAt, "Project retirement retiredAt");
+    }
+    else if (project.retirement !== undefined) {
+        throw new Error(`Active Project must not carry a retirement record: ${project.id}.`);
+    }
     const references = new Set();
     for (const reference of [project.id, project.name, ...project.aliases]) {
         const folded = reference.toLocaleLowerCase();