@mcoda/codali 0.1.134 → 0.1.135-codali.4

package/dist/runtime/StructuralEvidence.d.ts

@@ -0,0 +1,22 @@
+export interface StructuralAnalysis {
+    kind: "structure" | "impact";
+    file: string;
+    hash: string;
+    valid: boolean;
+}
+export declare const isSourcePath: (file: string) => boolean;
+export declare const workspaceRelativePath: (root: string, file: string) => string;
+export declare const isWithinScope: (file: string, scope: string[]) => boolean;
+/** Git ignores cannot hide existing source from an explicitly writable directory. */
+export declare const writableInventory: (root: string, scopes: string[], maxEntries?: number) => Promise<Record<string, string>>;
+export declare const analysisTarget: (tool: string, args: Record<string, unknown>) => {
+    kind: StructuralAnalysis["kind"];
+    file: string;
+} | undefined;
+/** A successful transport alone is not structural evidence (parsers can skip files). */
+export declare const validAnalysisResult: (kind: StructuralAnalysis["kind"], data: unknown, file: string) => boolean;
+export declare const missingStructuralEvidence: (file: string, hash: string, receipts: Iterable<{
+    status: string;
+    analysis?: StructuralAnalysis;
+}>) => string[];
+//# sourceMappingURL=StructuralEvidence.d.ts.map

package/dist/runtime/StructuralEvidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StructuralEvidence.d.ts","sourceRoot":"","sources":["../../src/runtime/StructuralEvidence.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,OAA2I,CAAC;AAExL,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,MAIlE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,KAAG,OAA+E,CAAC;AAE9I,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,EAAE,QAAQ,MAAM,EAAE,EAAE,mBAAmB,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwB3H,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG;IAAE,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAIjI,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,GAAI,MAAM,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,OAAO,EAAE,MAAM,MAAM,KAAG,OAOnG,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,EAAE,UAAU,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CAAE,CAAC,KAAG,MAAM,EAQnJ,CAAC"}

package/dist/runtime/StructuralEvidence.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { hashWorkspacePath } from "./WorkspaceSnapshot.js";
+export const isSourcePath = (file) => /\.(?:[cm]?[jt]sx?|py|rs|go|java|kt|kts|c|cc|cpp|cxx|h|hpp|cs|rb|php|swift|sh|bash|lua|ex|exs|scala|sc|vue|svelte)$/i.test(file);
+export const workspaceRelativePath = (root, file) => {
+    const relative = path.relative(root, path.resolve(root, file)).split(path.sep).join("/");
+    if (relative === ".." || relative.startsWith("../") || path.isAbsolute(relative))
+        throw new Error("Path escapes the workspace");
+    return relative || ".";
+};
+export const isWithinScope = (file, scope) => scope.some(p => p === "." || p === file || file.startsWith(`${p}/`));
+/** Git ignores cannot hide existing source from an explicitly writable directory. */
+export const writableInventory = async (root, scopes, maxEntries = 20000) => {
+    root = await fs.realpath(root);
+    const hashes = {};
+    const visited = new Set();
+    const walk = async (file) => {
+        if ([".git", ".mcoda"].some(dir => file === dir || file.startsWith(`${dir}/`)) || visited.has(file))
+            return;
+        visited.add(file);
+        if (visited.size > maxEntries)
+            throw new Error("Shell write inventory exceeds its bound; declare narrower writePaths");
+        const absolute = path.resolve(root, file);
+        let stat;
+        try {
+            stat = await fs.lstat(absolute);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        if (stat.isDirectory()) {
+            for (const entry of await fs.readdir(absolute))
+                await walk(workspaceRelativePath(root, path.join(absolute, entry)));
+        }
+        else {
+            if (stat.isFile() && stat.nlink > 1)
+                throw new Error(`Hard-linked writable file requires an independent copy: ${file}`);
+            hashes[file] = await hashWorkspacePath(root, file);
+        }
+    };
+    for (const scope of scopes) {
+        const relative = workspaceRelativePath(root, scope);
+        const requested = path.resolve(root, relative);
+        try {
+            if (await fs.realpath(requested) !== requested)
+                throw new Error("Shell write paths must be canonical and cannot be symlink aliases");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        await walk(relative);
+    }
+    return hashes;
+};
+export const analysisTarget = (tool, args) => {
+    if (["docdex_symbols", "docdex_ast"].includes(tool) && typeof args.path === "string")
+        return { kind: "structure", file: args.path };
+    if (tool === "docdex_impact_graph" && typeof args.file === "string")
+        return { kind: "impact", file: args.file };
+    return undefined;
+};
+/** A successful transport alone is not structural evidence (parsers can skip files). */
+export const validAnalysisResult = (kind, data, file) => {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return false;
+    const value = data;
+    if (value.error || value.isError)
+        return false;
+    if (kind === "impact")
+        return value.source === file && Array.isArray(value.edges) && Array.isArray(value.inbound) && Array.isArray(value.outbound);
+    const outcome = value.outcome;
+    return value.file === file && outcome?.status === "ok" && (Array.isArray(value.symbols) || Array.isArray(value.nodes));
+};
+export const missingStructuralEvidence = (file, hash, receipts) => {
+    if (hash === "missing" || !isSourcePath(file))
+        return [];
+    const present = new Set();
+    for (const receipt of receipts) {
+        const a = receipt.analysis;
+        if (receipt.status === "success" && a?.valid && a.file === file && a.hash === hash)
+            present.add(a.kind);
+    }
+    return ["structure", "impact"].filter(kind => !present.has(kind));
+};

package/dist/runtime/TaskReviewContext.d.ts

@@ -0,0 +1,34 @@
+import type { WorkState, WorkTask } from "../session/WorkTypes.js";
+/** Scope the review question without weakening the controller's global freshness checks. */
+export declare function taskReviewContext(state: WorkState, task: WorkTask, input: {
+    changedPaths: string[];
+    observedPaths: string[];
+    contextPaths: string[];
+    currentHashes: Record<string, string>;
+}): {
+    reviewScope: string;
+    goal: string | undefined;
+    goalReference: {
+        id: string;
+        revision: number;
+        planRevision: number;
+    };
+    requirements: import("../session/WorkTypes.js").Requirement[];
+    constraints: string[];
+    nonGoals: string[];
+    decisions: import("../session/WorkTypes.js").DecisionRecord[];
+    deferredRequirements: {
+        id: string;
+        owners: {
+            taskId: string;
+            status: import("../session/WorkTypes.js").WorkTaskStatus;
+        }[];
+    }[];
+    changedPaths: string[];
+    otherTaskChangedPaths: string[];
+    reviewPaths: string[];
+    sourceRoles: {
+        [k: string]: string;
+    };
+};
+//# sourceMappingURL=TaskReviewContext.d.ts.map

package/dist/runtime/TaskReviewContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskReviewContext.d.ts","sourceRoot":"","sources":["../../src/runtime/TaskReviewContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAInE,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE;IACzE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;;;;;;;;;;;;;;;;;;;;;;;;;EA8BA"}

package/dist/runtime/TaskReviewContext.js

@@ -0,0 +1,34 @@
+import { isTestSourcePath } from "./RequestedTestEvidence.js";
+import { isWithinScope } from "./StructuralEvidence.js";
+/** Scope the review question without weakening the controller's global freshness checks. */
+export function taskReviewContext(state, task, input) {
+    const requirements = state.requirements.filter(requirement => task.requirementIds.includes(requirement.id));
+    const wholeGoal = requirements.some(requirement => requirement.description === state.originalObjective);
+    const inScope = (file) => wholeGoal || isWithinScope(file, task.allowedPaths);
+    const changedPaths = input.changedPaths.filter(inScope);
+    const reviewPaths = [...new Set([
+            ...changedPaths,
+            ...Object.keys(input.currentHashes).filter(file => inScope(file) && isTestSourcePath(file)),
+            ...input.observedPaths.filter(inScope),
+            ...input.contextPaths,
+        ])];
+    const superseded = new Set(state.decisions.map(decision => decision.supersedes).filter(Boolean));
+    const decisions = state.decisions.filter(decision => !superseded.has(decision.id) && (wholeGoal || !decision.paths.length
+        || decision.paths.some(file => isWithinScope(file, task.allowedPaths)
+            || task.allowedPaths.some(scope => isWithinScope(scope, [file]))
+            || reviewPaths.some(observed => isWithinScope(observed, [file])))));
+    return {
+        reviewScope: wholeGoal ? "whole_goal" : "assigned_task",
+        goal: wholeGoal ? state.objective : undefined,
+        goalReference: { id: state.goalId, revision: state.goalRevision, planRevision: state.planRevision ?? 1 },
+        requirements, constraints: state.constraints, nonGoals: state.nonGoals, decisions,
+        deferredRequirements: wholeGoal ? [] : state.requirements.filter(requirement => !task.requirementIds.includes(requirement.id))
+            .map(requirement => ({ id: requirement.id, owners: state.tasks.filter(owner => owner.requirementIds.includes(requirement.id)
+                && !["cancelled", "superseded"].includes(owner.status)).map(owner => ({ taskId: owner.id, status: owner.status })) })),
+        changedPaths,
+        otherTaskChangedPaths: input.changedPaths.filter(file => !inScope(file)),
+        reviewPaths,
+        sourceRoles: Object.fromEntries(reviewPaths.map(file => [file, changedPaths.includes(file) ? "reviewed_change"
+                : inScope(file) ? "scope_context" : "read_only_context"])),
+    };
+}

package/dist/runtime/ValidationOutput.d.ts

@@ -0,0 +1,5 @@
+/** Bounded diagnostic context, never a substitute for the original receipt or
+ * its exit status. Preserve the failing region when passing checks fill the
+ * beginning of a long test log. */
+export declare function validationOutputExcerpt(output: string, maximum?: number): string;
+//# sourceMappingURL=ValidationOutput.d.ts.map

package/dist/runtime/ValidationOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationOutput.d.ts","sourceRoot":"","sources":["../../src/runtime/ValidationOutput.ts"],"names":[],"mappings":"AAAA;;mCAEmC;AACnC,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,MAAM,CAwB9E"}

package/dist/runtime/ValidationOutput.js

@@ -0,0 +1,32 @@
+/** Bounded diagnostic context, never a substitute for the original receipt or
+ * its exit status. Preserve the failing region when passing checks fill the
+ * beginning of a long test log. */
+export function validationOutputExcerpt(output, maximum = 2400) {
+    if (!Number.isInteger(maximum) || maximum < 600 || maximum > 8000)
+        throw new RangeError("Invalid validation excerpt bound");
+    if (output.length <= maximum)
+        return output;
+    output = output.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "");
+    if (output.length <= maximum)
+        return output;
+    const marker = "\n[... output omitted from this excerpt ...]\n";
+    const strong = /^(?:\s*not ok\s+\d|\s*FAIL(?:ED)?\s|\s*=+\s*FAILURES\s*=+|\s*error\[E\d+\]|.*: error (?:TS\d+|[A-Z]\d+):?)/m;
+    const fallback = /^(?:\s*(?:AssertionError|TypeError|Error):|.*panicked at)/m;
+    const failure = strong.exec(output) ?? fallback.exec(output);
+    if (!failure) {
+        const available = maximum - marker.length;
+        const head = Math.floor(available * 0.55);
+        return output.slice(0, head) + marker + output.slice(-(available - head));
+    }
+    const headSize = Math.min(180, Math.floor(maximum * 0.15));
+    const tailSize = Math.min(400, Math.floor(maximum * 0.2));
+    const windowSize = maximum - headSize - tailSize - marker.length * 2;
+    const start = Math.max(0, failure.index - Math.min(80, Math.floor(windowSize * 0.15)));
+    const end = Math.min(output.length, start + windowSize);
+    // Regions cannot overlap. Keeping an unused few characters is preferable to
+    // duplicating log content or trimming the failure after assembly.
+    const head = output.slice(0, Math.min(headSize, start));
+    const tailStart = Math.max(end, output.length - tailSize);
+    const tail = output.slice(tailStart);
+    return head + (start > head.length ? marker : "") + output.slice(start, end) + (tailStart > end ? marker : "") + tail;
+}

package/dist/runtime/VerificationCommand.d.ts

@@ -0,0 +1,5 @@
+/** Budget eligibility for inspection only; never substitutes for test evidence. */
+export declare const isVerificationInspectionCommand: (args: unknown) => boolean;
+/** Command-shape eligibility only; success, fresh input hashes and review remain mandatory. */
+export declare const isVerificationCommand: (args: unknown) => boolean;
+//# sourceMappingURL=VerificationCommand.d.ts.map

package/dist/runtime/VerificationCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VerificationCommand.d.ts","sourceRoot":"","sources":["../../src/runtime/VerificationCommand.ts"],"names":[],"mappings":"AAEA,mFAAmF;AACnF,eAAO,MAAM,+BAA+B,GAAI,MAAM,OAAO,KAAG,OAiB/D,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,qBAAqB,GAAI,MAAM,OAAO,KAAG,OA6BrD,CAAC"}

package/dist/runtime/VerificationCommand.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+/** Budget eligibility for inspection only; never substitutes for test evidence. */
+export const isVerificationInspectionCommand = (args) => {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return false;
+    const value = args;
+    if (value.command !== "git" || !Array.isArray(value.args) || value.args.some(arg => typeof arg !== "string"))
+        return false;
+    if (value.writePaths !== undefined && (!Array.isArray(value.writePaths) || value.writePaths.length !== 0))
+        return false;
+    const argv = value.args;
+    const flags = argv[0] === "diff"
+        ? ["--no-ext-diff", "--no-textconv", "--no-color", "--stat", "--name-only", "--name-status", "--check", "--cached", "--staged"]
+        : argv[0] === "status" ? ["--short", "--porcelain", "--porcelain=v1", "--porcelain=v2", "--branch"] : undefined;
+    if (!flags)
+        return false;
+    let paths = false;
+    for (const arg of argv.slice(1)) {
+        if (paths) {
+            if (!arg)
+                return false;
+        }
+        else if (arg === "--")
+            paths = true;
+        else if (!flags.includes(arg))
+            return false;
+    }
+    return true;
+};
+/** Command-shape eligibility only; success, fresh input hashes and review remain mandatory. */
+export const isVerificationCommand = (args) => {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return false;
+    const value = args;
+    if (typeof value.command !== "string" || value.args !== undefined && (!Array.isArray(value.args) || value.args.some(arg => typeof arg !== "string")))
+        return false;
+    const command = path.basename(value.command);
+    const argv = (value.args ?? []);
+    if (argv.some(arg => /^(?:--help|-h|--version|--dry-run|--if-present|--collect-only|--collectonly|--listTests|--list-tests|--showConfig|--listFilesOnly)(?:=|$)/.test(arg)))
+        return false;
+    if (["npm", "pnpm", "yarn", "bun"].includes(command)) {
+        let offset = 0;
+        const directoryFlags = command === "npm" ? ["--prefix"] : command === "pnpm" ? ["--dir", "-C"] : ["--cwd"];
+        while (offset < argv.length) {
+            if (["--silent", "-s", "--quiet", "-q", "--no-progress"].includes(argv[offset])) {
+                offset++;
+                continue;
+            }
+            if (directoryFlags.includes(argv[offset])) {
+                if (!argv[offset + 1] || argv[offset + 1].startsWith("-"))
+                    return false;
+                offset += 2;
+                continue;
+            }
+            if (directoryFlags.some(flag => argv[offset].startsWith(`${flag}=`) && argv[offset].length > flag.length + 1)) {
+                offset++;
+                continue;
+            }
+            break;
+        }
+        return argv[offset] === "test" || argv[offset] === "run" && /^(test|check|typecheck|lint)(:|$)/.test(argv[offset + 1] ?? "");
+    }
+    if (command === "node") {
+        let offset = 0;
+        while (["--no-warnings", "--enable-source-maps"].includes(argv[offset]))
+            offset++;
+        return argv[offset] === "--test" || /(?:^|\/)\S+\.(?:test|spec)\.[cm]?js$/.test(argv[offset] ?? "");
+    }
+    if (command === "pytest")
+        return !argv.includes("-V");
+    if (command === "tsc")
+        return !argv.includes("-v");
+    if (["cargo", "go", "make"].includes(command))
+        return argv[0] === "test";
+    return command === "python3" && argv[0] === "-m" && ["pytest", "unittest"].includes(argv[1]);
+};

package/dist/runtime/WorkStatusPage.d.ts

@@ -0,0 +1,15 @@
+import type { WorkState } from "../session/WorkTypes.js";
+export interface WorkStatusQuery {
+    offset?: number;
+    limit?: number;
+    taskIds?: string[];
+    requirementIds?: string[];
+    record?: "goal" | "task" | "requirement" | "decision" | "phase" | "constraints";
+    recordId?: string;
+    textOffset?: number;
+    textLimit?: number;
+}
+/** Inspection must remain available even when the whole goal cannot fit in a
+ * model context. Previews are explicit; record chunks retrieve the exact JSON. */
+export declare function workStatusPage(state: WorkState, query: WorkStatusQuery): Record<string, unknown>;
+//# sourceMappingURL=WorkStatusPage.d.ts.map

package/dist/runtime/WorkStatusPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkStatusPage.d.ts","sourceRoot":"","sources":["../../src/runtime/WorkStatusPage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;kFACkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8ChG"}

package/dist/runtime/WorkStatusPage.js

@@ -0,0 +1,58 @@
+/** Inspection must remain available even when the whole goal cannot fit in a
+ * model context. Previews are explicit; record chunks retrieve the exact JSON. */
+export function workStatusPage(state, query) {
+    const offset = query.offset ?? 0, limit = query.limit ?? 20;
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+        throw new Error("Invalid status page");
+    if (query.record) {
+        const record = query.record === "goal" ? { goalId: state.goalId, goalRevision: state.goalRevision, originalObjective: state.originalObjective, objective: state.objective }
+            : query.record === "constraints" ? { constraints: state.constraints, nonGoals: state.nonGoals }
+                : (() => {
+                    const records = query.record === "task" ? state.tasks : query.record === "requirement" ? state.requirements : query.record === "decision" ? state.decisions : state.phases ?? [];
+                    return query.recordId ? records.find(item => item.id === query.recordId) : records;
+                })();
+        if (!record)
+            throw new Error("Unknown status record; supply its exact recordId");
+        const encoded = JSON.stringify(record), start = query.textOffset ?? 0, size = query.textLimit ?? 6000;
+        if (!Number.isSafeInteger(start) || start < 0 || start > encoded.length || !Number.isSafeInteger(size) || size < 1 || size > 6000)
+            throw new Error("Invalid status record text range");
+        const content = encoded.slice(start, start + size);
+        return { record: query.record, recordId: query.recordId, encoding: "json", content, textOffset: start,
+            totalChars: encoded.length, nextTextOffset: start + content.length < encoded.length ? start + content.length : null };
+    }
+    const tasks = state.tasks.filter(task => !query.taskIds || query.taskIds.includes(task.id));
+    const candidates = tasks.slice(offset, offset + limit);
+    const ids = new Set(query.requirementIds ?? candidates.flatMap(task => task.requirementIds));
+    const requirements = state.requirements.filter(requirement => ids.has(requirement.id));
+    const view = {
+        goalId: state.goalId, goalRevision: state.goalRevision, planRevision: state.planRevision ?? 1, status: state.status,
+        originalObjective: state.originalObjective.slice(0, 1200), originalObjectiveTruncated: state.originalObjective.length > 1200,
+        objective: state.objective.slice(0, 1200), objectiveTruncated: state.objective.length > 1200,
+        tasks: [], requirements: [],
+        totalTasks: tasks.length, totalRequirements: state.requirements.length,
+        totalDecisions: state.decisions.length, totalPhases: state.phases?.length ?? 0,
+        totalConstraints: state.constraints.length, totalNonGoals: state.nonGoals.length,
+        nextOffset: null, omittedRequirements: 0,
+        continuation: "This is a bounded inspection page, not the complete contract. Use offset/limit or taskIds/requirementIds for records. Use record:goal|constraints|task|requirement|decision|phase, recordId and textOffset to retrieve exact JSON in chunks. Every canonical requirement remains mandatory.",
+    };
+    const preview = (item) => JSON.stringify(item).length <= 2500 ? item
+        : { id: item.id, status: item.status, title: typeof item.title === "string" ? item.title.slice(0, 240) : undefined,
+            description: typeof item.description === "string" ? item.description.slice(0, 600) : undefined, recordTruncated: true };
+    for (const task of candidates) {
+        view.tasks.push(preview({ ...task }));
+        if (JSON.stringify(view).length > 9000) {
+            view.tasks.pop();
+            break;
+        }
+    }
+    view.nextOffset = offset + view.tasks.length < tasks.length ? offset + view.tasks.length : null;
+    for (const requirement of requirements) {
+        view.requirements.push(preview({ ...requirement }));
+        if (JSON.stringify(view).length > 12000) {
+            view.requirements.pop();
+            break;
+        }
+    }
+    view.omittedRequirements = requirements.length - view.requirements.length;
+    return view;
+}

package/dist/runtime/WorkspaceLedger.d.ts

@@ -0,0 +1,13 @@
+import { type WorkspaceSnapshot } from "./WorkspaceSnapshot.js";
+/** Private original contents separate the agent's diff from a dirty checkout. */
+export declare class WorkspaceLedger {
+    readonly root: string;
+    readonly workspaceRoot: string;
+    constructor(root: string, workspaceRoot: string);
+    private get manifest();
+    private read;
+    private readWorkspaceContent;
+    capture(snapshot: WorkspaceSnapshot, scopes: string[], explicitPaths?: string[]): Promise<void>;
+    diff(files: string[], limit?: number): Promise<string>;
+}
+//# sourceMappingURL=WorkspaceLedger.d.ts.map

package/dist/runtime/WorkspaceLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceLedger.d.ts","sourceRoot":"","sources":["../../src/runtime/WorkspaceLedger.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAOlG,iFAAiF;AACjF,qBAAa,eAAe;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM;gBAA5C,IAAI,EAAE,MAAM,EAAW,aAAa,EAAE,MAAM;IAGjE,OAAO,KAAK,QAAQ,GAA6D;YACnE,IAAI;YAUJ,oBAAoB;IAoB5B,OAAO,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,aAAa,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BnG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;CA+B7D"}

package/dist/runtime/WorkspaceLedger.js

@@ -0,0 +1,145 @@
+import { constants, promises as fs, realpathSync } from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { atomicWriteJson, withStateLock } from "../session/AtomicState.js";
+import { hashWorkspacePath, workspaceHash } from "./WorkspaceSnapshot.js";
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const inScope = (file, scopes) => scopes.some(scope => scope === "." || file === scope || file.startsWith(`${scope}/`));
+/** Private original contents separate the agent's diff from a dirty checkout. */
+export class WorkspaceLedger {
+    constructor(root, workspaceRoot) {
+        this.root = root;
+        this.workspaceRoot = workspaceRoot;
+        this.workspaceRoot = realpathSync.native(workspaceRoot);
+    }
+    get manifest() { return path.join(this.root, "ownership.json"); }
+    async read() {
+        try {
+            const value = JSON.parse(await fs.readFile(this.manifest, "utf8"));
+            if (value.schemaVersion !== 1 || !value.files)
+                throw new Error("Invalid workspace ownership ledger");
+            if (value.knownPaths !== undefined && (!Array.isArray(value.knownPaths) || value.knownPaths.some(file => typeof file !== "string" || path.isAbsolute(file) || file.split(/[\\/]/).includes(".."))))
+                throw new Error("Invalid workspace baseline inventory");
+            for (const [file, entry] of Object.entries(value.files))
+                if (path.isAbsolute(file) || file.split(/[\\/]/).includes("..") || !entry || typeof entry.hash !== "string" || entry.blob && !/^[a-f0-9]{64}$/.test(entry.blob))
+                    throw new Error("Invalid workspace preimage reference");
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { schemaVersion: 1, files: {} };
+            throw error;
+        }
+    }
+    async readWorkspaceContent(file, expectedHash) {
+        const target = path.resolve(this.workspaceRoot, file);
+        const parent = await fs.realpath(path.dirname(target));
+        if (!target.startsWith(`${this.workspaceRoot}${path.sep}`) || parent !== this.workspaceRoot && !parent.startsWith(`${this.workspaceRoot}${path.sep}`))
+            throw new Error("Workspace preimage path escapes the repository");
+        const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const before = await handle.stat();
+            if (!before.isFile() || before.size > MAX_FILE_BYTES)
+                throw new Error("Workspace content exceeds the 8 MiB file limit");
+            const chunks = [];
+            let bytes = 0;
+            for await (const chunk of handle.createReadStream({ autoClose: false })) {
+                bytes += chunk.length;
+                if (bytes > MAX_FILE_BYTES)
+                    throw new Error("Workspace content exceeds the 8 MiB file limit");
+                chunks.push(Buffer.from(chunk));
+            }
+            const after = await handle.stat();
+            const content = Buffer.concat(chunks);
+            if (before.size !== after.size || before.ctimeMs !== after.ctimeMs || workspaceHash(content) !== expectedHash)
+                throw new Error(`File changed while preparing the edit or diff: ${file}`);
+            return content;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async capture(snapshot, scopes, explicitPaths = []) {
+        await withStateLock(this.manifest, async () => {
+            const record = await this.read();
+            record.knownPaths ?? (record.knownPaths = Object.keys(snapshot.hashes));
+            const candidates = new Set([...Object.keys(snapshot.hashes).filter(file => inScope(file, scopes)), ...explicitPaths]);
+            let bytes = Object.values(record.files).reduce((sum, entry) => sum + (entry.bytes ?? 0), 0);
+            for (const file of candidates) {
+                if (record.files[file])
+                    continue;
+                const hash = snapshot.hashes[file] ?? await hashWorkspacePath(this.workspaceRoot, file);
+                const entry = { hash };
+                if (/^[a-f0-9]{64}$/.test(hash)) {
+                    const stat = await fs.lstat(path.join(this.workspaceRoot, file));
+                    if (stat.size > 8 * 1024 * 1024 || bytes + stat.size > 64 * 1024 * 1024)
+                        throw new Error("Task preimages exceed the 64 MiB ledger or 8 MiB file limit; narrow the task scope");
+                    const content = await this.readWorkspaceContent(file, hash);
+                    if (workspaceHash(content) !== hash || await hashWorkspacePath(this.workspaceRoot, file) !== hash)
+                        throw new Error(`File changed while preparing the edit: ${file}`);
+                    const blob = path.join(this.root, "blobs", hash);
+                    await fs.mkdir(path.dirname(blob), { recursive: true, mode: 0o700 });
+                    try {
+                        await fs.writeFile(blob, content, { flag: "wx", mode: 0o600 });
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST")
+                            throw error;
+                    }
+                    entry.blob = hash;
+                    entry.bytes = content.length;
+                    bytes += content.length;
+                }
+                record.files[file] = entry;
+            }
+            await atomicWriteJson(this.manifest, record);
+        });
+    }
+    async diff(files, limit = 60000) {
+        const record = await this.read();
+        const sections = [];
+        let length = 0;
+        await fs.mkdir(this.root, { recursive: true, mode: 0o700 });
+        for (const file of files) {
+            if (length >= limit)
+                break;
+            const entry = record.files[file] ?? (record.knownPaths && !record.knownPaths.includes(file) ? { hash: "missing" } : undefined);
+            if (!entry)
+                throw new Error(`No saved preimage for ${file}; session ownership cannot be established`);
+            const currentHash = await hashWorkspacePath(this.workspaceRoot, file);
+            if (currentHash === entry.hash)
+                continue;
+            if ((!entry.blob && entry.hash !== "missing") || currentHash.startsWith("symlink:") || currentHash.startsWith("directory:")) {
+                const summary = `${file}: ${entry.hash} -> ${currentHash}\n`;
+                sections.push(summary);
+                length += summary.length;
+                continue;
+            }
+            if (currentHash !== "missing" && (await fs.lstat(path.join(this.workspaceRoot, file))).size > MAX_FILE_BYTES) {
+                const summary = `${file}: ${entry.hash} -> ${currentHash} (content diff omitted above 8 MiB; validate the artifact separately)\n`;
+                sections.push(summary);
+                length += summary.length;
+                continue;
+            }
+            const directory = await fs.mkdtemp(path.join(this.root, "diff-"));
+            try {
+                const before = entry.blob ? await fs.readFile(path.join(this.root, "blobs", entry.blob)) : Buffer.alloc(0);
+                const after = currentHash === "missing" ? Buffer.alloc(0) : await this.readWorkspaceContent(file, currentHash);
+                if (entry.blob && workspaceHash(before) !== entry.hash)
+                    throw new Error("Workspace preimage checksum mismatch");
+                if (after.length && workspaceHash(after) !== currentHash)
+                    throw new Error(`File changed during diff: ${file}`);
+                await fs.writeFile(path.join(directory, "before"), before, { mode: 0o600 });
+                await fs.writeFile(path.join(directory, "after"), after, { mode: 0o600 });
+                const diff = await new Promise((resolve, reject) => execFile("git", ["--no-pager", "diff", "--no-index", "--no-ext-diff", "--no-textconv", "--", "before", "after"], { cwd: directory, timeout: 10000, maxBuffer: 32 * 1024 * 1024, env: { PATH: process.env.PATH, LANG: "C", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" } }, (error, stdout) => error && error.code !== 1 ? reject(error) : resolve(stdout)));
+                const section = `Session changes: ${JSON.stringify(file)}\n${diff}`.slice(0, limit - length);
+                sections.push(section);
+                length += section.length;
+            }
+            finally {
+                await fs.rm(directory, { recursive: true, force: true });
+            }
+        }
+        return sections.join("\n");
+    }
+}

package/dist/runtime/WorkspaceLock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkspaceLock.d.ts","sourceRoot":"","sources":["../../src/runtime/WorkspaceLock.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC;CACxD;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAPlB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;gBAGhC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAuB;YAK7B,QAAQ;IAStB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;YAcR,iBAAiB;YAuBjB,mBAAmB;IAQ3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,sBAAsB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,IAAI;CAmC7E"}
+{"version":3,"file":"WorkspaceLock.d.ts","sourceRoot":"","sources":["../../src/runtime/WorkspaceLock.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC;CACxD;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAPlB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;gBAGhC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAuB;YAK7B,QAAQ;IAStB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;YAcR,iBAAiB;YAuBjB,mBAAmB;IAQ3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,sBAAsB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,IAAI;CAmC7E"}

package/dist/runtime/WorkspaceLock.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { withStateLock } from "../session/AtomicState.js";
 export class WorkspaceLock {
     constructor(workspaceRoot, runId, maxAgeMs = 60 * 60 * 1000) {
         this.workspaceRoot = workspaceRoot;
@@ -69,32 +70,34 @@ export class WorkspaceLock {
         return false;
     }
     async shouldClearExisting(info) {
-        if (this.isStale(info))
-            return true;
         const processAlive = this.isProcessAlive(info);
         if (processAlive === false)
             return true;
         if (processAlive === true)
             return false;
+        if (this.isStale(info) && this.isSameHost(info))
+            return this.hasTerminalRunLog(info.runId);
         return this.hasTerminalRunLog(info.runId);
     }
     async acquire() {
         await fs.mkdir(path.dirname(this.lockPath), { recursive: true });
-        const existing = await this.readLock();
-        if (existing && !(await this.shouldClearExisting(existing))) {
-            throw new Error(`Workspace is locked by run ${existing.runId}`);
-        }
-        if (existing) {
-            await fs.unlink(this.lockPath).catch(() => undefined);
-        }
-        const payload = {
-            runId: this.runId,
-            acquiredAt: Date.now(),
-            pid: process.pid,
-            hostname: this.hostname,
-        };
-        await fs.writeFile(this.lockPath, JSON.stringify(payload, null, 2), "utf8");
-        this.acquired = true;
+        await withStateLock(`${this.lockPath}.transaction`, async () => {
+            const existing = await this.readLock();
+            if (existing && !(await this.shouldClearExisting(existing))) {
+                throw new Error(`Workspace is locked by run ${existing.runId}`);
+            }
+            if (existing) {
+                await fs.unlink(this.lockPath).catch(() => undefined);
+            }
+            const payload = {
+                runId: this.runId,
+                acquiredAt: Date.now(),
+                pid: process.pid,
+                hostname: this.hostname,
+            };
+            await fs.writeFile(this.lockPath, JSON.stringify(payload, null, 2), { encoding: "utf8", flag: "wx", mode: 0o600 });
+            this.acquired = true;
+        });
     }
     async release() {
         if (!this.acquired)