apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/verification-lifecycle.d.ts

@@ -0,0 +1,77 @@
+/**
+ * VF.4: the verification lifecycle (spec
+ * 2026-09-01-configured-verification-and-formatting.md § 4). The tracker
+ * turns bounded executor outcomes into the five completion statuses the
+ * spec names — verified, failed, unavailable, interrupted,
+ * continued-unverified — and retires a result the moment the workspace it
+ * described changes. It never flips failed to passed, and a stale result
+ * never presents as current: the conservative rule is that ANY non-empty
+ * workspace change retires the record, because proving a change irrelevant
+ * is the executor's job, not the lifecycle's.
+ *
+ * Evidence is bounded by construction: the record carries policy identity,
+ * argv, status, duration, exit/signal/truncation flags, and the artifact
+ * reference — never raw output. Callers that want output read the artifact
+ * through the store's permission gate.
+ */
+import type { AuthorizeConfiguredCommand } from "./permissions/policy-command.ts";
+import type { PolicyRunStatus } from "./policy-executor.ts";
+import type { VerificationPolicy } from "./policy-loader.ts";
+import type { WorkspaceArtifactRef } from "./workspace/artifacts.ts";
+export type VerificationOutcome = "verified" | "failed" | "interrupted";
+export type VerificationCompletionStatus = "verified" | "failed" | "unavailable" | "interrupted" | "continued-unverified";
+export interface VerificationEvidence {
+    policyId: string;
+    executable: string;
+    argv: string[];
+    cwd: string;
+    status: PolicyRunStatus;
+    durationMs: number;
+    exitCode?: number;
+    signal?: string;
+    truncated: boolean;
+    artifact?: WorkspaceArtifactRef;
+}
+export interface VerificationRecord {
+    outcome: VerificationOutcome;
+    evidence: VerificationEvidence[];
+    observedAt: number;
+}
+export type VerificationBoundary = "explicit" | "post-turn";
+export interface VerificationTrackerOptions {
+    workspaceRoot: string;
+    /**
+     * PS.1. Absent only in tests and embeddings with no permission authority at
+     * all; a session that has a gate always supplies one, and a blocked policy
+     * then spawns nothing.
+     */
+    authorize?: AuthorizeConfiguredCommand;
+}
+export declare class VerificationTracker {
+    #private;
+    constructor(options: VerificationTrackerOptions);
+    configure(policies: VerificationPolicy[], boundary: VerificationBoundary): void;
+    get boundary(): VerificationBoundary;
+    policyIds(): string[];
+    /**
+     * Run one configured policy by id (default: the first). Returns the new
+     * record, or undefined when the id is not configured — surfaced as
+     * "unavailable" by completionStatus(). A run retires any earlier record
+     * and any earlier continue-without-verification choice.
+     */
+    runExplicit(policyId?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VerificationRecord | undefined>;
+    /** The user chose to finish without verification. Its own status, not a failure. */
+    recordContinuedWithoutVerification(): void;
+    /**
+     * Report a workspace change observed after the latest record. Any
+     * non-empty change set retires the record: the result described a
+     * workspace that no longer exists.
+     */
+    noteWorkspaceChange(changedPaths: ReadonlySet<string>): void;
+    completionStatus(): VerificationCompletionStatus;
+    /** The current record, if one is live. Stale results are not returned. */
+    latest(): VerificationRecord | undefined;
+}
+//# sourceMappingURL=verification-lifecycle.d.ts.map

package/dist/core/verification-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-lifecycle.d.ts","sourceRoot":"","sources":["../../src/core/verification-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;AAExE,MAAM,MAAM,4BAA4B,GACrC,UAAU,GACV,QAAQ,GACR,aAAa,GACb,aAAa,GACb,sBAAsB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,0BAA0B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,0BAA0B,CAAC;CACvC;AA2BD,qBAAa,mBAAmB;;IAQ/B,YAAY,OAAO,EAAE,0BAA0B,EAG9C;IAED,SAAS,CAAC,QAAQ,EAAE,kBAAkB,EAAE,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAG9E;IAED,IAAI,QAAQ,IAAI,oBAAoB,CAEnC;IAED,SAAS,IAAI,MAAM,EAAE,CAEpB;IAED;;;;;OAKG;IACG,WAAW,CAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACpC,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAezC;IAED,oFAAoF;IACpF,kCAAkC,IAAI,IAAI,CAGzC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAI3D;IAED,gBAAgB,IAAI,4BAA4B,CAY/C;IAED,0EAA0E;IAC1E,MAAM,IAAI,kBAAkB,GAAG,SAAS,CAEvC;CA+BD","sourcesContent":["/**\n * VF.4: the verification lifecycle (spec\n * 2026-09-01-configured-verification-and-formatting.md § 4). The tracker\n * turns bounded executor outcomes into the five completion statuses the\n * spec names — verified, failed, unavailable, interrupted,\n * continued-unverified — and retires a result the moment the workspace it\n * described changes. It never flips failed to passed, and a stale result\n * never presents as current: the conservative rule is that ANY non-empty\n * workspace change retires the record, because proving a change irrelevant\n * is the executor's job, not the lifecycle's.\n *\n * Evidence is bounded by construction: the record carries policy identity,\n * argv, status, duration, exit/signal/truncation flags, and the artifact\n * reference — never raw output. Callers that want output read the artifact\n * through the store's permission gate.\n */\n\nimport type { AuthorizeConfiguredCommand } from \"./permissions/policy-command.ts\";\nimport type { PolicyRunOutcome, PolicyRunStatus } from \"./policy-executor.ts\";\nimport { runPolicyCommand } from \"./policy-executor.ts\";\nimport type { VerificationPolicy } from \"./policy-loader.ts\";\nimport type { WorkspaceArtifactRef } from \"./workspace/artifacts.ts\";\n\nexport type VerificationOutcome = \"verified\" | \"failed\" | \"interrupted\";\n\nexport type VerificationCompletionStatus =\n\t| \"verified\"\n\t| \"failed\"\n\t| \"unavailable\"\n\t| \"interrupted\"\n\t| \"continued-unverified\";\n\nexport interface VerificationEvidence {\n\tpolicyId: string;\n\texecutable: string;\n\targv: string[];\n\tcwd: string;\n\tstatus: PolicyRunStatus;\n\tdurationMs: number;\n\texitCode?: number;\n\tsignal?: string;\n\ttruncated: boolean;\n\tartifact?: WorkspaceArtifactRef;\n}\n\nexport interface VerificationRecord {\n\toutcome: VerificationOutcome;\n\tevidence: VerificationEvidence[];\n\tobservedAt: number;\n}\n\nexport type VerificationBoundary = \"explicit\" | \"post-turn\";\n\nexport interface VerificationTrackerOptions {\n\tworkspaceRoot: string;\n\t/**\n\t * PS.1. Absent only in tests and embeddings with no permission authority at\n\t * all; a session that has a gate always supplies one, and a blocked policy\n\t * then spawns nothing.\n\t */\n\tauthorize?: AuthorizeConfiguredCommand;\n}\n\nfunction evidenceFor(outcome: PolicyRunOutcome): VerificationEvidence {\n\treturn {\n\t\tpolicyId: outcome.policyId,\n\t\texecutable: outcome.executable,\n\t\targv: outcome.argv,\n\t\tcwd: outcome.cwd,\n\t\tstatus: outcome.status,\n\t\tdurationMs: outcome.durationMs,\n\t\t...(outcome.exitCode !== undefined ? { exitCode: outcome.exitCode } : {}),\n\t\t...(outcome.signal !== undefined ? { signal: outcome.signal } : {}),\n\t\ttruncated: outcome.truncated,\n\t\t...(outcome.artifact !== undefined ? { artifact: outcome.artifact } : {}),\n\t};\n}\n\nfunction recordOutcome(outcome: PolicyRunOutcome): VerificationRecord {\n\tconst outcomeKind: VerificationOutcome =\n\t\toutcome.status === \"passed\" ? \"verified\" : outcome.status === \"failed\" ? \"failed\" : \"interrupted\";\n\treturn {\n\t\toutcome: outcomeKind,\n\t\tevidence: [evidenceFor(outcome)],\n\t\tobservedAt: Date.now(),\n\t};\n}\n\nexport class VerificationTracker {\n\t#policies: VerificationPolicy[] = [];\n\t#boundary: VerificationBoundary = \"explicit\";\n\t#workspaceRoot: string;\n\t#latest: VerificationRecord | undefined;\n\t#continuedWithoutVerification = false;\n\t#authorize: AuthorizeConfiguredCommand | undefined;\n\n\tconstructor(options: VerificationTrackerOptions) {\n\t\tthis.#workspaceRoot = options.workspaceRoot;\n\t\tthis.#authorize = options.authorize;\n\t}\n\n\tconfigure(policies: VerificationPolicy[], boundary: VerificationBoundary): void {\n\t\tthis.#policies = [...policies];\n\t\tthis.#boundary = boundary;\n\t}\n\n\tget boundary(): VerificationBoundary {\n\t\treturn this.#boundary;\n\t}\n\n\tpolicyIds(): string[] {\n\t\treturn this.#policies.map((policy) => policy.id);\n\t}\n\n\t/**\n\t * Run one configured policy by id (default: the first). Returns the new\n\t * record, or undefined when the id is not configured — surfaced as\n\t * \"unavailable\" by completionStatus(). A run retires any earlier record\n\t * and any earlier continue-without-verification choice.\n\t */\n\tasync runExplicit(\n\t\tpolicyId?: string,\n\t\toptions: { signal?: AbortSignal } = {},\n\t): Promise<VerificationRecord | undefined> {\n\t\tconst policy =\n\t\t\tpolicyId === undefined ? this.#policies[0] : this.#policies.find((candidate) => candidate.id === policyId);\n\t\tif (policy === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\t\tthis.#continuedWithoutVerification = false;\n\t\tconst refusal = await this.#refuseUnauthorized(policy);\n\t\tif (refusal !== undefined) {\n\t\t\tthis.#latest = refusal;\n\t\t\treturn this.#latest;\n\t\t}\n\t\tconst outcome = await runPolicyCommand(policy, { workspaceRoot: this.#workspaceRoot, signal: options.signal });\n\t\tthis.#latest = recordOutcome(outcome);\n\t\treturn this.#latest;\n\t}\n\n\t/** The user chose to finish without verification. Its own status, not a failure. */\n\trecordContinuedWithoutVerification(): void {\n\t\tthis.#latest = undefined;\n\t\tthis.#continuedWithoutVerification = true;\n\t}\n\n\t/**\n\t * Report a workspace change observed after the latest record. Any\n\t * non-empty change set retires the record: the result described a\n\t * workspace that no longer exists.\n\t */\n\tnoteWorkspaceChange(changedPaths: ReadonlySet<string>): void {\n\t\tif (changedPaths.size > 0) {\n\t\t\tthis.#latest = undefined;\n\t\t}\n\t}\n\n\tcompletionStatus(): VerificationCompletionStatus {\n\t\tif (this.#continuedWithoutVerification) {\n\t\t\treturn \"continued-unverified\";\n\t\t}\n\t\tif (this.#latest === undefined) {\n\t\t\treturn \"unavailable\";\n\t\t}\n\t\treturn this.#latest.outcome === \"verified\"\n\t\t\t? \"verified\"\n\t\t\t: this.#latest.outcome === \"failed\"\n\t\t\t\t? \"failed\"\n\t\t\t\t: \"interrupted\";\n\t}\n\n\t/** The current record, if one is live. Stale results are not returned. */\n\tlatest(): VerificationRecord | undefined {\n\t\treturn this.#latest;\n\t}\n\n\t/** A record for a policy the permission authority blocked. Nothing was spawned, so it can never read as verified. */\n\tasync #refuseUnauthorized(policy: VerificationPolicy): Promise<VerificationRecord | undefined> {\n\t\tif (this.#authorize === undefined) return undefined;\n\t\tconst decision = await this.#authorize({\n\t\t\tpolicyId: policy.id,\n\t\t\texecutable: policy.executable,\n\t\t\targv: policy.argv,\n\t\t\tcwd: this.#workspaceRoot,\n\t\t\twriteScope: undefined,\n\t\t\tcapabilities: new Set([\"exec\"]),\n\t\t\tpermission: policy.permission,\n\t\t});\n\t\tif (!decision.block) return undefined;\n\t\treturn {\n\t\t\toutcome: \"interrupted\",\n\t\t\tevidence: [\n\t\t\t\t{\n\t\t\t\t\tpolicyId: policy.id,\n\t\t\t\t\texecutable: policy.executable,\n\t\t\t\t\targv: policy.argv,\n\t\t\t\t\tcwd: this.#workspaceRoot,\n\t\t\t\t\tstatus: \"refused\",\n\t\t\t\t\tdurationMs: 0,\n\t\t\t\t\ttruncated: false,\n\t\t\t\t},\n\t\t\t],\n\t\t\tobservedAt: Date.now(),\n\t\t};\n\t}\n}\n"]}

package/dist/core/verification-lifecycle.js

@@ -0,0 +1,146 @@
+/**
+ * VF.4: the verification lifecycle (spec
+ * 2026-09-01-configured-verification-and-formatting.md § 4). The tracker
+ * turns bounded executor outcomes into the five completion statuses the
+ * spec names — verified, failed, unavailable, interrupted,
+ * continued-unverified — and retires a result the moment the workspace it
+ * described changes. It never flips failed to passed, and a stale result
+ * never presents as current: the conservative rule is that ANY non-empty
+ * workspace change retires the record, because proving a change irrelevant
+ * is the executor's job, not the lifecycle's.
+ *
+ * Evidence is bounded by construction: the record carries policy identity,
+ * argv, status, duration, exit/signal/truncation flags, and the artifact
+ * reference — never raw output. Callers that want output read the artifact
+ * through the store's permission gate.
+ */
+import { runPolicyCommand } from "./policy-executor.js";
+function evidenceFor(outcome) {
+    return {
+        policyId: outcome.policyId,
+        executable: outcome.executable,
+        argv: outcome.argv,
+        cwd: outcome.cwd,
+        status: outcome.status,
+        durationMs: outcome.durationMs,
+        ...(outcome.exitCode !== undefined ? { exitCode: outcome.exitCode } : {}),
+        ...(outcome.signal !== undefined ? { signal: outcome.signal } : {}),
+        truncated: outcome.truncated,
+        ...(outcome.artifact !== undefined ? { artifact: outcome.artifact } : {}),
+    };
+}
+function recordOutcome(outcome) {
+    const outcomeKind = outcome.status === "passed" ? "verified" : outcome.status === "failed" ? "failed" : "interrupted";
+    return {
+        outcome: outcomeKind,
+        evidence: [evidenceFor(outcome)],
+        observedAt: Date.now(),
+    };
+}
+export class VerificationTracker {
+    #policies = [];
+    #boundary = "explicit";
+    #workspaceRoot;
+    #latest;
+    #continuedWithoutVerification = false;
+    #authorize;
+    constructor(options) {
+        this.#workspaceRoot = options.workspaceRoot;
+        this.#authorize = options.authorize;
+    }
+    configure(policies, boundary) {
+        this.#policies = [...policies];
+        this.#boundary = boundary;
+    }
+    get boundary() {
+        return this.#boundary;
+    }
+    policyIds() {
+        return this.#policies.map((policy) => policy.id);
+    }
+    /**
+     * Run one configured policy by id (default: the first). Returns the new
+     * record, or undefined when the id is not configured — surfaced as
+     * "unavailable" by completionStatus(). A run retires any earlier record
+     * and any earlier continue-without-verification choice.
+     */
+    async runExplicit(policyId, options = {}) {
+        const policy = policyId === undefined ? this.#policies[0] : this.#policies.find((candidate) => candidate.id === policyId);
+        if (policy === undefined) {
+            return undefined;
+        }
+        this.#continuedWithoutVerification = false;
+        const refusal = await this.#refuseUnauthorized(policy);
+        if (refusal !== undefined) {
+            this.#latest = refusal;
+            return this.#latest;
+        }
+        const outcome = await runPolicyCommand(policy, { workspaceRoot: this.#workspaceRoot, signal: options.signal });
+        this.#latest = recordOutcome(outcome);
+        return this.#latest;
+    }
+    /** The user chose to finish without verification. Its own status, not a failure. */
+    recordContinuedWithoutVerification() {
+        this.#latest = undefined;
+        this.#continuedWithoutVerification = true;
+    }
+    /**
+     * Report a workspace change observed after the latest record. Any
+     * non-empty change set retires the record: the result described a
+     * workspace that no longer exists.
+     */
+    noteWorkspaceChange(changedPaths) {
+        if (changedPaths.size > 0) {
+            this.#latest = undefined;
+        }
+    }
+    completionStatus() {
+        if (this.#continuedWithoutVerification) {
+            return "continued-unverified";
+        }
+        if (this.#latest === undefined) {
+            return "unavailable";
+        }
+        return this.#latest.outcome === "verified"
+            ? "verified"
+            : this.#latest.outcome === "failed"
+                ? "failed"
+                : "interrupted";
+    }
+    /** The current record, if one is live. Stale results are not returned. */
+    latest() {
+        return this.#latest;
+    }
+    /** A record for a policy the permission authority blocked. Nothing was spawned, so it can never read as verified. */
+    async #refuseUnauthorized(policy) {
+        if (this.#authorize === undefined)
+            return undefined;
+        const decision = await this.#authorize({
+            policyId: policy.id,
+            executable: policy.executable,
+            argv: policy.argv,
+            cwd: this.#workspaceRoot,
+            writeScope: undefined,
+            capabilities: new Set(["exec"]),
+            permission: policy.permission,
+        });
+        if (!decision.block)
+            return undefined;
+        return {
+            outcome: "interrupted",
+            evidence: [
+                {
+                    policyId: policy.id,
+                    executable: policy.executable,
+                    argv: policy.argv,
+                    cwd: this.#workspaceRoot,
+                    status: "refused",
+                    durationMs: 0,
+                    truncated: false,
+                },
+            ],
+            observedAt: Date.now(),
+        };
+    }
+}
+//# sourceMappingURL=verification-lifecycle.js.map

package/dist/core/verification-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-lifecycle.js","sourceRoot":"","sources":["../../src/core/verification-lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * VF.4: the verification lifecycle (spec\n * 2026-09-01-configured-verification-and-formatting.md § 4). The tracker\n * turns bounded executor outcomes into the five completion statuses the\n * spec names — verified, failed, unavailable, interrupted,\n * continued-unverified — and retires a result the moment the workspace it\n * described changes. It never flips failed to passed, and a stale result\n * never presents as current: the conservative rule is that ANY non-empty\n * workspace change retires the record, because proving a change irrelevant\n * is the executor's job, not the lifecycle's.\n *\n * Evidence is bounded by construction: the record carries policy identity,\n * argv, status, duration, exit/signal/truncation flags, and the artifact\n * reference — never raw output. Callers that want output read the artifact\n * through the store's permission gate.\n */\n\nimport type { AuthorizeConfiguredCommand } from \"./permissions/policy-command.ts\";\nimport type { PolicyRunOutcome, PolicyRunStatus } from \"./policy-executor.ts\";\nimport { runPolicyCommand } from \"./policy-executor.ts\";\nimport type { VerificationPolicy } from \"./policy-loader.ts\";\nimport type { WorkspaceArtifactRef } from \"./workspace/artifacts.ts\";\n\nexport type VerificationOutcome = \"verified\" | \"failed\" | \"interrupted\";\n\nexport type VerificationCompletionStatus =\n\t| \"verified\"\n\t| \"failed\"\n\t| \"unavailable\"\n\t| \"interrupted\"\n\t| \"continued-unverified\";\n\nexport interface VerificationEvidence {\n\tpolicyId: string;\n\texecutable: string;\n\targv: string[];\n\tcwd: string;\n\tstatus: PolicyRunStatus;\n\tdurationMs: number;\n\texitCode?: number;\n\tsignal?: string;\n\ttruncated: boolean;\n\tartifact?: WorkspaceArtifactRef;\n}\n\nexport interface VerificationRecord {\n\toutcome: VerificationOutcome;\n\tevidence: VerificationEvidence[];\n\tobservedAt: number;\n}\n\nexport type VerificationBoundary = \"explicit\" | \"post-turn\";\n\nexport interface VerificationTrackerOptions {\n\tworkspaceRoot: string;\n\t/**\n\t * PS.1. Absent only in tests and embeddings with no permission authority at\n\t * all; a session that has a gate always supplies one, and a blocked policy\n\t * then spawns nothing.\n\t */\n\tauthorize?: AuthorizeConfiguredCommand;\n}\n\nfunction evidenceFor(outcome: PolicyRunOutcome): VerificationEvidence {\n\treturn {\n\t\tpolicyId: outcome.policyId,\n\t\texecutable: outcome.executable,\n\t\targv: outcome.argv,\n\t\tcwd: outcome.cwd,\n\t\tstatus: outcome.status,\n\t\tdurationMs: outcome.durationMs,\n\t\t...(outcome.exitCode !== undefined ? { exitCode: outcome.exitCode } : {}),\n\t\t...(outcome.signal !== undefined ? { signal: outcome.signal } : {}),\n\t\ttruncated: outcome.truncated,\n\t\t...(outcome.artifact !== undefined ? { artifact: outcome.artifact } : {}),\n\t};\n}\n\nfunction recordOutcome(outcome: PolicyRunOutcome): VerificationRecord {\n\tconst outcomeKind: VerificationOutcome =\n\t\toutcome.status === \"passed\" ? \"verified\" : outcome.status === \"failed\" ? \"failed\" : \"interrupted\";\n\treturn {\n\t\toutcome: outcomeKind,\n\t\tevidence: [evidenceFor(outcome)],\n\t\tobservedAt: Date.now(),\n\t};\n}\n\nexport class VerificationTracker {\n\t#policies: VerificationPolicy[] = [];\n\t#boundary: VerificationBoundary = \"explicit\";\n\t#workspaceRoot: string;\n\t#latest: VerificationRecord | undefined;\n\t#continuedWithoutVerification = false;\n\t#authorize: AuthorizeConfiguredCommand | undefined;\n\n\tconstructor(options: VerificationTrackerOptions) {\n\t\tthis.#workspaceRoot = options.workspaceRoot;\n\t\tthis.#authorize = options.authorize;\n\t}\n\n\tconfigure(policies: VerificationPolicy[], boundary: VerificationBoundary): void {\n\t\tthis.#policies = [...policies];\n\t\tthis.#boundary = boundary;\n\t}\n\n\tget boundary(): VerificationBoundary {\n\t\treturn this.#boundary;\n\t}\n\n\tpolicyIds(): string[] {\n\t\treturn this.#policies.map((policy) => policy.id);\n\t}\n\n\t/**\n\t * Run one configured policy by id (default: the first). Returns the new\n\t * record, or undefined when the id is not configured — surfaced as\n\t * \"unavailable\" by completionStatus(). A run retires any earlier record\n\t * and any earlier continue-without-verification choice.\n\t */\n\tasync runExplicit(\n\t\tpolicyId?: string,\n\t\toptions: { signal?: AbortSignal } = {},\n\t): Promise<VerificationRecord | undefined> {\n\t\tconst policy =\n\t\t\tpolicyId === undefined ? this.#policies[0] : this.#policies.find((candidate) => candidate.id === policyId);\n\t\tif (policy === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\t\tthis.#continuedWithoutVerification = false;\n\t\tconst refusal = await this.#refuseUnauthorized(policy);\n\t\tif (refusal !== undefined) {\n\t\t\tthis.#latest = refusal;\n\t\t\treturn this.#latest;\n\t\t}\n\t\tconst outcome = await runPolicyCommand(policy, { workspaceRoot: this.#workspaceRoot, signal: options.signal });\n\t\tthis.#latest = recordOutcome(outcome);\n\t\treturn this.#latest;\n\t}\n\n\t/** The user chose to finish without verification. Its own status, not a failure. */\n\trecordContinuedWithoutVerification(): void {\n\t\tthis.#latest = undefined;\n\t\tthis.#continuedWithoutVerification = true;\n\t}\n\n\t/**\n\t * Report a workspace change observed after the latest record. Any\n\t * non-empty change set retires the record: the result described a\n\t * workspace that no longer exists.\n\t */\n\tnoteWorkspaceChange(changedPaths: ReadonlySet<string>): void {\n\t\tif (changedPaths.size > 0) {\n\t\t\tthis.#latest = undefined;\n\t\t}\n\t}\n\n\tcompletionStatus(): VerificationCompletionStatus {\n\t\tif (this.#continuedWithoutVerification) {\n\t\t\treturn \"continued-unverified\";\n\t\t}\n\t\tif (this.#latest === undefined) {\n\t\t\treturn \"unavailable\";\n\t\t}\n\t\treturn this.#latest.outcome === \"verified\"\n\t\t\t? \"verified\"\n\t\t\t: this.#latest.outcome === \"failed\"\n\t\t\t\t? \"failed\"\n\t\t\t\t: \"interrupted\";\n\t}\n\n\t/** The current record, if one is live. Stale results are not returned. */\n\tlatest(): VerificationRecord | undefined {\n\t\treturn this.#latest;\n\t}\n\n\t/** A record for a policy the permission authority blocked. Nothing was spawned, so it can never read as verified. */\n\tasync #refuseUnauthorized(policy: VerificationPolicy): Promise<VerificationRecord | undefined> {\n\t\tif (this.#authorize === undefined) return undefined;\n\t\tconst decision = await this.#authorize({\n\t\t\tpolicyId: policy.id,\n\t\t\texecutable: policy.executable,\n\t\t\targv: policy.argv,\n\t\t\tcwd: this.#workspaceRoot,\n\t\t\twriteScope: undefined,\n\t\t\tcapabilities: new Set([\"exec\"]),\n\t\t\tpermission: policy.permission,\n\t\t});\n\t\tif (!decision.block) return undefined;\n\t\treturn {\n\t\t\toutcome: \"interrupted\",\n\t\t\tevidence: [\n\t\t\t\t{\n\t\t\t\t\tpolicyId: policy.id,\n\t\t\t\t\texecutable: policy.executable,\n\t\t\t\t\targv: policy.argv,\n\t\t\t\t\tcwd: this.#workspaceRoot,\n\t\t\t\t\tstatus: \"refused\",\n\t\t\t\t\tdurationMs: 0,\n\t\t\t\t\ttruncated: false,\n\t\t\t\t},\n\t\t\t],\n\t\t\tobservedAt: Date.now(),\n\t\t};\n\t}\n}\n"]}

package/dist/core/workspace/artifacts.d.ts

@@ -0,0 +1,45 @@
+export interface WorkspaceArtifactRef {
+    artifactId: string;
+    /** File name inside the store directory; never a path with separators. */
+    file: string;
+    sha256: string;
+    bytes: number;
+}
+export type WorkspaceArtifactPermission = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+export type WorkspaceArtifactRead = {
+    ok: true;
+    bytes: Buffer;
+} | {
+    ok: false;
+    reason: "denied" | "missing" | "integrity" | "invalid-ref";
+};
+export interface WriteArtifactOptions {
+    /** Reject payloads larger than this (default: settings default). */
+    maxBytes?: number;
+    /** Retention count cap applied after the write (default: settings default). */
+    maxArtifacts?: number;
+    /** Retention total-bytes cap applied after the write (default: settings default). */
+    maxTotalBytes?: number;
+    signal?: AbortSignal;
+}
+export interface StoredArtifactInfo {
+    file: string;
+    bytes: number;
+}
+/** `<dir>/<session-basename>.artifacts/workspace-state` next to a session file. */
+export declare function workspaceArtifactDirFor(sessionFile: string): string;
+export declare class WorkspaceArtifactStore {
+    #private;
+    readonly dir: string;
+    constructor(sessionFile: string);
+    writeArtifact(bytes: Buffer, options?: WriteArtifactOptions): Promise<WorkspaceArtifactRef>;
+    readArtifact(ref: WorkspaceArtifactRef, permission: WorkspaceArtifactPermission): Promise<WorkspaceArtifactRead>;
+    listArtifactsSync(): StoredArtifactInfo[];
+    removeAll(): Promise<void>;
+}
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/core/workspace/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/core/workspace/artifacts.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,2BAA2B,GACpC;IACA,OAAO,EAAE,IAAI,CAAC;CACb,GACD;IACA,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CACd,CAAC;AAEL,MAAM,MAAM,qBAAqB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACpC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACd;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGnE;AAMD,qBAAa,sBAAsB;;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAGrB,YAAY,WAAW,EAAE,MAAM,EAE9B;IAsDK,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkChG;IAEK,YAAY,CACjB,GAAG,EAAE,oBAAoB,EACzB,UAAU,EAAE,2BAA2B,GACrC,OAAO,CAAC,qBAAqB,CAAC,CAqBhC;IAED,iBAAiB,IAAI,kBAAkB,EAAE,CAExC;IAEK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/B;CACD","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport {\n\texistsSync,\n\tmkdirSync,\n\treaddirSync,\n\treadFileSync,\n\trenameSync,\n\trmSync,\n\tstatSync,\n\tunlinkSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { basename, dirname, join } from \"node:path\";\nimport {\n\tDEFAULT_WORKSPACE_MAX_ARTIFACTS,\n\tDEFAULT_WORKSPACE_MAX_PATCH_BYTES,\n\tDEFAULT_WORKSPACE_MAX_TOTAL_BYTES,\n} from \"../settings-manager.ts\";\n\n/**\n * Durable workspace artifact store (WS.3, spec\n * 2026-09-01-harness-correctness-and-workspace-state.md § 2).\n *\n * This is the named owner for workspace-state artifacts. It is scoped to one\n * session file (`<basename>.artifacts/workspace-state/` next to the session\n * JSONL) and guarantees:\n *\n * - atomic publish (unique temp file in the target directory, `rename(2)`,\n *   hash verified after publish; interrupted writes leave only `.tmp` files\n *   that are ignored and cleaned up by the next write);\n * - restrictive permissions (directory 0o700, files 0o600 on platforms that\n *   enforce them);\n * - integrity (sha256 + byte length in the reference; a mismatch reads as\n *   `integrity` failure, never as bytes);\n * - bounded retention (FIFO by count and by total bytes; `.tmp` leftovers do\n *   not count);\n * - permission-gated retrieval (the caller must pass an explicit permission\n *   decision; a denied read never probes the filesystem, so denial leaks no\n *   existence oracle).\n *\n * Artifact references confer no permission by themselves: content reaches a\n * provider or a tool only through the normal permission system and output\n * bounds at the consuming surface. Patch bytes never enter the session JSONL\n * or the evidence ledger.\n */\n\nconst FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\nconst TMP_SUFFIX = \".tmp\";\n\nexport interface WorkspaceArtifactRef {\n\tartifactId: string;\n\t/** File name inside the store directory; never a path with separators. */\n\tfile: string;\n\tsha256: string;\n\tbytes: number;\n}\n\nexport type WorkspaceArtifactPermission =\n\t| {\n\t\t\tallowed: true;\n\t  }\n\t| {\n\t\t\tallowed: false;\n\t\t\treason: string;\n\t  };\n\nexport type WorkspaceArtifactRead =\n\t| { ok: true; bytes: Buffer }\n\t| { ok: false; reason: \"denied\" | \"missing\" | \"integrity\" | \"invalid-ref\" };\n\nexport interface WriteArtifactOptions {\n\t/** Reject payloads larger than this (default: settings default). */\n\tmaxBytes?: number;\n\t/** Retention count cap applied after the write (default: settings default). */\n\tmaxArtifacts?: number;\n\t/** Retention total-bytes cap applied after the write (default: settings default). */\n\tmaxTotalBytes?: number;\n\tsignal?: AbortSignal;\n}\n\nexport interface StoredArtifactInfo {\n\tfile: string;\n\tbytes: number;\n}\n\n/** `<dir>/<session-basename>.artifacts/workspace-state` next to a session file. */\nexport function workspaceArtifactDirFor(sessionFile: string): string {\n\tconst base = basename(sessionFile).replace(/\\.jsonl$/, \"\");\n\treturn join(dirname(sessionFile), `${base}.artifacts`, \"workspace-state\");\n}\n\nfunction sha256Hex(bytes: Buffer): string {\n\treturn `sha256:${createHash(\"sha256\").update(bytes).digest(\"hex\")}`;\n}\n\nexport class WorkspaceArtifactStore {\n\treadonly dir: string;\n\t#counter = 0;\n\n\tconstructor(sessionFile: string) {\n\t\tthis.dir = workspaceArtifactDirFor(sessionFile);\n\t}\n\n\t#validFileName(file: string): boolean {\n\t\treturn FILE_PATTERN.test(file) && !file.endsWith(TMP_SUFFIX) && !file.includes(\"..\");\n\t}\n\n\t#listStored(): StoredArtifactInfo[] {\n\t\tif (!existsSync(this.dir)) return [];\n\t\tconst stored: StoredArtifactInfo[] = [];\n\t\tfor (const file of readdirSync(this.dir)) {\n\t\t\tif (!this.#validFileName(file)) continue;\n\t\t\tconst full = join(this.dir, file);\n\t\t\tconst stat = statSync(full);\n\t\t\tif (!stat.isFile()) continue;\n\t\t\tstored.push({ file, bytes: stat.size });\n\t\t}\n\t\t// File names embed a sortable write sequence\n\t\t// (`<time>-<counter>-<artifactId>.patch`), so lexicographic order is\n\t\t// chronological regardless of filesystem timestamp granularity.\n\t\tstored.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));\n\t\treturn stored;\n\t}\n\n\t#removeStaleTemp(): void {\n\t\tif (!existsSync(this.dir)) return;\n\t\tfor (const file of readdirSync(this.dir)) {\n\t\t\tif (file.endsWith(TMP_SUFFIX)) {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(join(this.dir, file));\n\t\t\t\t} catch {\n\t\t\t\t\t// A concurrent writer owns it; leave it for the next pass.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t#prune(maxArtifacts: number, maxTotalBytes: number): void {\n\t\tconst stored = this.#listStored();\n\t\tlet total = stored.reduce((sum, info) => sum + info.bytes, 0);\n\t\tlet excessCount = stored.length - maxArtifacts;\n\t\tfor (const info of stored) {\n\t\t\tif (excessCount <= 0 && total <= maxTotalBytes) break;\n\t\t\tif (excessCount > 0 || total > maxTotalBytes) {\n\t\t\t\ttry {\n\t\t\t\t\trmSync(join(this.dir, info.file), { force: true });\n\t\t\t\t\ttotal -= info.bytes;\n\t\t\t\t\texcessCount--;\n\t\t\t\t} catch {\n\t\t\t\t\t// Unlinkable now; the next write retries.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tasync writeArtifact(bytes: Buffer, options?: WriteArtifactOptions): Promise<WorkspaceArtifactRef> {\n\t\tif (options?.signal?.aborted) {\n\t\t\tthrow new Error(\"workspace artifact write cancelled\");\n\t\t}\n\t\tconst maxBytes = options?.maxBytes ?? DEFAULT_WORKSPACE_MAX_PATCH_BYTES;\n\t\tif (bytes.byteLength > maxBytes) {\n\t\t\tthrow new Error(`workspace artifact exceeds the configured cap (${bytes.byteLength} > ${maxBytes} bytes)`);\n\t\t}\n\t\tconst maxArtifacts = options?.maxArtifacts ?? DEFAULT_WORKSPACE_MAX_ARTIFACTS;\n\t\tconst maxTotalBytes = options?.maxTotalBytes ?? DEFAULT_WORKSPACE_MAX_TOTAL_BYTES;\n\n\t\tmkdirSync(this.dir, { recursive: true, mode: 0o700 });\n\t\tthis.#removeStaleTemp();\n\n\t\tconst artifactId = randomUUID();\n\t\tconst sequence = `${Date.now().toString(36).padStart(8, \"0\")}-${(this.#counter++).toString(36).padStart(4, \"0\")}`;\n\t\tconst file = `${sequence}-${artifactId}.patch`;\n\t\tconst finalPath = join(this.dir, file);\n\t\tconst tempPath = join(this.dir, `${artifactId}${TMP_SUFFIX}`);\n\t\tconst expected = sha256Hex(bytes);\n\t\twriteFileSync(tempPath, bytes, { mode: 0o600 });\n\t\t// Atomic publish: readers only ever see the final name.\n\t\trenameSync(tempPath, finalPath);\n\t\t// Integrity check on our own publish path: a silent corruption or a\n\t\t// truncating filesystem must not leave a reference that reads back\n\t\t// different bytes.\n\t\tconst written = readFileSync(finalPath);\n\t\tif (sha256Hex(written) !== expected || written.byteLength !== bytes.byteLength) {\n\t\t\trmSync(finalPath, { force: true });\n\t\t\tthrow new Error(\"workspace artifact failed its post-publish integrity check\");\n\t\t}\n\n\t\tthis.#prune(maxArtifacts, maxTotalBytes);\n\t\treturn { artifactId, file, sha256: expected, bytes: bytes.byteLength };\n\t}\n\n\tasync readArtifact(\n\t\tref: WorkspaceArtifactRef,\n\t\tpermission: WorkspaceArtifactPermission,\n\t): Promise<WorkspaceArtifactRead> {\n\t\t// Permission is checked before any filesystem access so denial cannot\n\t\t// leak existence through a missing-vs-present distinction.\n\t\tif (!permission.allowed) {\n\t\t\treturn { ok: false, reason: \"denied\" };\n\t\t}\n\t\tif (typeof ref?.file !== \"string\" || !this.#validFileName(ref.file)) {\n\t\t\treturn { ok: false, reason: \"invalid-ref\" };\n\t\t}\n\t\tconst full = join(this.dir, ref.file);\n\t\tlet bytes: Buffer;\n\t\ttry {\n\t\t\tif (!existsSync(full)) return { ok: false, reason: \"missing\" };\n\t\t\tbytes = readFileSync(full);\n\t\t} catch {\n\t\t\treturn { ok: false, reason: \"missing\" };\n\t\t}\n\t\tif (bytes.byteLength !== ref.bytes || sha256Hex(bytes) !== ref.sha256) {\n\t\t\treturn { ok: false, reason: \"integrity\" };\n\t\t}\n\t\treturn { ok: true, bytes };\n\t}\n\n\tlistArtifactsSync(): StoredArtifactInfo[] {\n\t\treturn this.#listStored();\n\t}\n\n\tasync removeAll(): Promise<void> {\n\t\trmSync(this.dir, { recursive: true, force: true });\n\t}\n}\n"]}

package/dist/core/workspace/artifacts.js

@@ -0,0 +1,165 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { DEFAULT_WORKSPACE_MAX_ARTIFACTS, DEFAULT_WORKSPACE_MAX_PATCH_BYTES, DEFAULT_WORKSPACE_MAX_TOTAL_BYTES, } from "../settings-manager.js";
+/**
+ * Durable workspace artifact store (WS.3, spec
+ * 2026-09-01-harness-correctness-and-workspace-state.md § 2).
+ *
+ * This is the named owner for workspace-state artifacts. It is scoped to one
+ * session file (`<basename>.artifacts/workspace-state/` next to the session
+ * JSONL) and guarantees:
+ *
+ * - atomic publish (unique temp file in the target directory, `rename(2)`,
+ *   hash verified after publish; interrupted writes leave only `.tmp` files
+ *   that are ignored and cleaned up by the next write);
+ * - restrictive permissions (directory 0o700, files 0o600 on platforms that
+ *   enforce them);
+ * - integrity (sha256 + byte length in the reference; a mismatch reads as
+ *   `integrity` failure, never as bytes);
+ * - bounded retention (FIFO by count and by total bytes; `.tmp` leftovers do
+ *   not count);
+ * - permission-gated retrieval (the caller must pass an explicit permission
+ *   decision; a denied read never probes the filesystem, so denial leaks no
+ *   existence oracle).
+ *
+ * Artifact references confer no permission by themselves: content reaches a
+ * provider or a tool only through the normal permission system and output
+ * bounds at the consuming surface. Patch bytes never enter the session JSONL
+ * or the evidence ledger.
+ */
+const FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TMP_SUFFIX = ".tmp";
+/** `<dir>/<session-basename>.artifacts/workspace-state` next to a session file. */
+export function workspaceArtifactDirFor(sessionFile) {
+    const base = basename(sessionFile).replace(/\.jsonl$/, "");
+    return join(dirname(sessionFile), `${base}.artifacts`, "workspace-state");
+}
+function sha256Hex(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+export class WorkspaceArtifactStore {
+    dir;
+    #counter = 0;
+    constructor(sessionFile) {
+        this.dir = workspaceArtifactDirFor(sessionFile);
+    }
+    #validFileName(file) {
+        return FILE_PATTERN.test(file) && !file.endsWith(TMP_SUFFIX) && !file.includes("..");
+    }
+    #listStored() {
+        if (!existsSync(this.dir))
+            return [];
+        const stored = [];
+        for (const file of readdirSync(this.dir)) {
+            if (!this.#validFileName(file))
+                continue;
+            const full = join(this.dir, file);
+            const stat = statSync(full);
+            if (!stat.isFile())
+                continue;
+            stored.push({ file, bytes: stat.size });
+        }
+        // File names embed a sortable write sequence
+        // (`<time>-<counter>-<artifactId>.patch`), so lexicographic order is
+        // chronological regardless of filesystem timestamp granularity.
+        stored.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+        return stored;
+    }
+    #removeStaleTemp() {
+        if (!existsSync(this.dir))
+            return;
+        for (const file of readdirSync(this.dir)) {
+            if (file.endsWith(TMP_SUFFIX)) {
+                try {
+                    unlinkSync(join(this.dir, file));
+                }
+                catch {
+                    // A concurrent writer owns it; leave it for the next pass.
+                }
+            }
+        }
+    }
+    #prune(maxArtifacts, maxTotalBytes) {
+        const stored = this.#listStored();
+        let total = stored.reduce((sum, info) => sum + info.bytes, 0);
+        let excessCount = stored.length - maxArtifacts;
+        for (const info of stored) {
+            if (excessCount <= 0 && total <= maxTotalBytes)
+                break;
+            if (excessCount > 0 || total > maxTotalBytes) {
+                try {
+                    rmSync(join(this.dir, info.file), { force: true });
+                    total -= info.bytes;
+                    excessCount--;
+                }
+                catch {
+                    // Unlinkable now; the next write retries.
+                }
+            }
+        }
+    }
+    async writeArtifact(bytes, options) {
+        if (options?.signal?.aborted) {
+            throw new Error("workspace artifact write cancelled");
+        }
+        const maxBytes = options?.maxBytes ?? DEFAULT_WORKSPACE_MAX_PATCH_BYTES;
+        if (bytes.byteLength > maxBytes) {
+            throw new Error(`workspace artifact exceeds the configured cap (${bytes.byteLength} > ${maxBytes} bytes)`);
+        }
+        const maxArtifacts = options?.maxArtifacts ?? DEFAULT_WORKSPACE_MAX_ARTIFACTS;
+        const maxTotalBytes = options?.maxTotalBytes ?? DEFAULT_WORKSPACE_MAX_TOTAL_BYTES;
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        this.#removeStaleTemp();
+        const artifactId = randomUUID();
+        const sequence = `${Date.now().toString(36).padStart(8, "0")}-${(this.#counter++).toString(36).padStart(4, "0")}`;
+        const file = `${sequence}-${artifactId}.patch`;
+        const finalPath = join(this.dir, file);
+        const tempPath = join(this.dir, `${artifactId}${TMP_SUFFIX}`);
+        const expected = sha256Hex(bytes);
+        writeFileSync(tempPath, bytes, { mode: 0o600 });
+        // Atomic publish: readers only ever see the final name.
+        renameSync(tempPath, finalPath);
+        // Integrity check on our own publish path: a silent corruption or a
+        // truncating filesystem must not leave a reference that reads back
+        // different bytes.
+        const written = readFileSync(finalPath);
+        if (sha256Hex(written) !== expected || written.byteLength !== bytes.byteLength) {
+            rmSync(finalPath, { force: true });
+            throw new Error("workspace artifact failed its post-publish integrity check");
+        }
+        this.#prune(maxArtifacts, maxTotalBytes);
+        return { artifactId, file, sha256: expected, bytes: bytes.byteLength };
+    }
+    async readArtifact(ref, permission) {
+        // Permission is checked before any filesystem access so denial cannot
+        // leak existence through a missing-vs-present distinction.
+        if (!permission.allowed) {
+            return { ok: false, reason: "denied" };
+        }
+        if (typeof ref?.file !== "string" || !this.#validFileName(ref.file)) {
+            return { ok: false, reason: "invalid-ref" };
+        }
+        const full = join(this.dir, ref.file);
+        let bytes;
+        try {
+            if (!existsSync(full))
+                return { ok: false, reason: "missing" };
+            bytes = readFileSync(full);
+        }
+        catch {
+            return { ok: false, reason: "missing" };
+        }
+        if (bytes.byteLength !== ref.bytes || sha256Hex(bytes) !== ref.sha256) {
+            return { ok: false, reason: "integrity" };
+        }
+        return { ok: true, bytes };
+    }
+    listArtifactsSync() {
+        return this.#listStored();
+    }
+    async removeAll() {
+        rmSync(this.dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/core/workspace/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../src/core/workspace/artifacts.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport {\n\texistsSync,\n\tmkdirSync,\n\treaddirSync,\n\treadFileSync,\n\trenameSync,\n\trmSync,\n\tstatSync,\n\tunlinkSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { basename, dirname, join } from \"node:path\";\nimport {\n\tDEFAULT_WORKSPACE_MAX_ARTIFACTS,\n\tDEFAULT_WORKSPACE_MAX_PATCH_BYTES,\n\tDEFAULT_WORKSPACE_MAX_TOTAL_BYTES,\n} from \"../settings-manager.ts\";\n\n/**\n * Durable workspace artifact store (WS.3, spec\n * 2026-09-01-harness-correctness-and-workspace-state.md § 2).\n *\n * This is the named owner for workspace-state artifacts. It is scoped to one\n * session file (`<basename>.artifacts/workspace-state/` next to the session\n * JSONL) and guarantees:\n *\n * - atomic publish (unique temp file in the target directory, `rename(2)`,\n *   hash verified after publish; interrupted writes leave only `.tmp` files\n *   that are ignored and cleaned up by the next write);\n * - restrictive permissions (directory 0o700, files 0o600 on platforms that\n *   enforce them);\n * - integrity (sha256 + byte length in the reference; a mismatch reads as\n *   `integrity` failure, never as bytes);\n * - bounded retention (FIFO by count and by total bytes; `.tmp` leftovers do\n *   not count);\n * - permission-gated retrieval (the caller must pass an explicit permission\n *   decision; a denied read never probes the filesystem, so denial leaks no\n *   existence oracle).\n *\n * Artifact references confer no permission by themselves: content reaches a\n * provider or a tool only through the normal permission system and output\n * bounds at the consuming surface. Patch bytes never enter the session JSONL\n * or the evidence ledger.\n */\n\nconst FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\nconst TMP_SUFFIX = \".tmp\";\n\nexport interface WorkspaceArtifactRef {\n\tartifactId: string;\n\t/** File name inside the store directory; never a path with separators. */\n\tfile: string;\n\tsha256: string;\n\tbytes: number;\n}\n\nexport type WorkspaceArtifactPermission =\n\t| {\n\t\t\tallowed: true;\n\t  }\n\t| {\n\t\t\tallowed: false;\n\t\t\treason: string;\n\t  };\n\nexport type WorkspaceArtifactRead =\n\t| { ok: true; bytes: Buffer }\n\t| { ok: false; reason: \"denied\" | \"missing\" | \"integrity\" | \"invalid-ref\" };\n\nexport interface WriteArtifactOptions {\n\t/** Reject payloads larger than this (default: settings default). */\n\tmaxBytes?: number;\n\t/** Retention count cap applied after the write (default: settings default). */\n\tmaxArtifacts?: number;\n\t/** Retention total-bytes cap applied after the write (default: settings default). */\n\tmaxTotalBytes?: number;\n\tsignal?: AbortSignal;\n}\n\nexport interface StoredArtifactInfo {\n\tfile: string;\n\tbytes: number;\n}\n\n/** `<dir>/<session-basename>.artifacts/workspace-state` next to a session file. */\nexport function workspaceArtifactDirFor(sessionFile: string): string {\n\tconst base = basename(sessionFile).replace(/\\.jsonl$/, \"\");\n\treturn join(dirname(sessionFile), `${base}.artifacts`, \"workspace-state\");\n}\n\nfunction sha256Hex(bytes: Buffer): string {\n\treturn `sha256:${createHash(\"sha256\").update(bytes).digest(\"hex\")}`;\n}\n\nexport class WorkspaceArtifactStore {\n\treadonly dir: string;\n\t#counter = 0;\n\n\tconstructor(sessionFile: string) {\n\t\tthis.dir = workspaceArtifactDirFor(sessionFile);\n\t}\n\n\t#validFileName(file: string): boolean {\n\t\treturn FILE_PATTERN.test(file) && !file.endsWith(TMP_SUFFIX) && !file.includes(\"..\");\n\t}\n\n\t#listStored(): StoredArtifactInfo[] {\n\t\tif (!existsSync(this.dir)) return [];\n\t\tconst stored: StoredArtifactInfo[] = [];\n\t\tfor (const file of readdirSync(this.dir)) {\n\t\t\tif (!this.#validFileName(file)) continue;\n\t\t\tconst full = join(this.dir, file);\n\t\t\tconst stat = statSync(full);\n\t\t\tif (!stat.isFile()) continue;\n\t\t\tstored.push({ file, bytes: stat.size });\n\t\t}\n\t\t// File names embed a sortable write sequence\n\t\t// (`<time>-<counter>-<artifactId>.patch`), so lexicographic order is\n\t\t// chronological regardless of filesystem timestamp granularity.\n\t\tstored.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));\n\t\treturn stored;\n\t}\n\n\t#removeStaleTemp(): void {\n\t\tif (!existsSync(this.dir)) return;\n\t\tfor (const file of readdirSync(this.dir)) {\n\t\t\tif (file.endsWith(TMP_SUFFIX)) {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(join(this.dir, file));\n\t\t\t\t} catch {\n\t\t\t\t\t// A concurrent writer owns it; leave it for the next pass.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t#prune(maxArtifacts: number, maxTotalBytes: number): void {\n\t\tconst stored = this.#listStored();\n\t\tlet total = stored.reduce((sum, info) => sum + info.bytes, 0);\n\t\tlet excessCount = stored.length - maxArtifacts;\n\t\tfor (const info of stored) {\n\t\t\tif (excessCount <= 0 && total <= maxTotalBytes) break;\n\t\t\tif (excessCount > 0 || total > maxTotalBytes) {\n\t\t\t\ttry {\n\t\t\t\t\trmSync(join(this.dir, info.file), { force: true });\n\t\t\t\t\ttotal -= info.bytes;\n\t\t\t\t\texcessCount--;\n\t\t\t\t} catch {\n\t\t\t\t\t// Unlinkable now; the next write retries.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tasync writeArtifact(bytes: Buffer, options?: WriteArtifactOptions): Promise<WorkspaceArtifactRef> {\n\t\tif (options?.signal?.aborted) {\n\t\t\tthrow new Error(\"workspace artifact write cancelled\");\n\t\t}\n\t\tconst maxBytes = options?.maxBytes ?? DEFAULT_WORKSPACE_MAX_PATCH_BYTES;\n\t\tif (bytes.byteLength > maxBytes) {\n\t\t\tthrow new Error(`workspace artifact exceeds the configured cap (${bytes.byteLength} > ${maxBytes} bytes)`);\n\t\t}\n\t\tconst maxArtifacts = options?.maxArtifacts ?? DEFAULT_WORKSPACE_MAX_ARTIFACTS;\n\t\tconst maxTotalBytes = options?.maxTotalBytes ?? DEFAULT_WORKSPACE_MAX_TOTAL_BYTES;\n\n\t\tmkdirSync(this.dir, { recursive: true, mode: 0o700 });\n\t\tthis.#removeStaleTemp();\n\n\t\tconst artifactId = randomUUID();\n\t\tconst sequence = `${Date.now().toString(36).padStart(8, \"0\")}-${(this.#counter++).toString(36).padStart(4, \"0\")}`;\n\t\tconst file = `${sequence}-${artifactId}.patch`;\n\t\tconst finalPath = join(this.dir, file);\n\t\tconst tempPath = join(this.dir, `${artifactId}${TMP_SUFFIX}`);\n\t\tconst expected = sha256Hex(bytes);\n\t\twriteFileSync(tempPath, bytes, { mode: 0o600 });\n\t\t// Atomic publish: readers only ever see the final name.\n\t\trenameSync(tempPath, finalPath);\n\t\t// Integrity check on our own publish path: a silent corruption or a\n\t\t// truncating filesystem must not leave a reference that reads back\n\t\t// different bytes.\n\t\tconst written = readFileSync(finalPath);\n\t\tif (sha256Hex(written) !== expected || written.byteLength !== bytes.byteLength) {\n\t\t\trmSync(finalPath, { force: true });\n\t\t\tthrow new Error(\"workspace artifact failed its post-publish integrity check\");\n\t\t}\n\n\t\tthis.#prune(maxArtifacts, maxTotalBytes);\n\t\treturn { artifactId, file, sha256: expected, bytes: bytes.byteLength };\n\t}\n\n\tasync readArtifact(\n\t\tref: WorkspaceArtifactRef,\n\t\tpermission: WorkspaceArtifactPermission,\n\t): Promise<WorkspaceArtifactRead> {\n\t\t// Permission is checked before any filesystem access so denial cannot\n\t\t// leak existence through a missing-vs-present distinction.\n\t\tif (!permission.allowed) {\n\t\t\treturn { ok: false, reason: \"denied\" };\n\t\t}\n\t\tif (typeof ref?.file !== \"string\" || !this.#validFileName(ref.file)) {\n\t\t\treturn { ok: false, reason: \"invalid-ref\" };\n\t\t}\n\t\tconst full = join(this.dir, ref.file);\n\t\tlet bytes: Buffer;\n\t\ttry {\n\t\t\tif (!existsSync(full)) return { ok: false, reason: \"missing\" };\n\t\t\tbytes = readFileSync(full);\n\t\t} catch {\n\t\t\treturn { ok: false, reason: \"missing\" };\n\t\t}\n\t\tif (bytes.byteLength !== ref.bytes || sha256Hex(bytes) !== ref.sha256) {\n\t\t\treturn { ok: false, reason: \"integrity\" };\n\t\t}\n\t\treturn { ok: true, bytes };\n\t}\n\n\tlistArtifactsSync(): StoredArtifactInfo[] {\n\t\treturn this.#listStored();\n\t}\n\n\tasync removeAll(): Promise<void> {\n\t\trmSync(this.dir, { recursive: true, force: true });\n\t}\n}\n"]}

package/dist/core/workspace/comparison.d.ts

@@ -0,0 +1,27 @@
+import type { WorkspaceStateComparison, WorkspaceStateRecord } from "./state.ts";
+import { WORKSPACE_RECORD_VERSION } from "./state.ts";
+/** Upper bound on `changedPaths` carried in one comparison record. */
+export declare const MAX_CHANGED_PATHS = 200;
+export type WorkspaceComparisonOutcome = Pick<WorkspaceStateComparison, "result" | "changedPaths" | "warnings">;
+export interface WorkspaceComparisonOptions {
+    /** Probe for stored patch artifacts; defaults to existence on disk. */
+    artifactProbe?: (storePath: string) => boolean;
+}
+/**
+ * WS.5: compare fresh workspace state against a stored observation (spec
+ * 2026-09-01-harness-correctness-and-workspace-state.md § 3). Pure: same
+ * inputs, same outcome. `unavailable` — the workspace could not be observed
+ * now; `inconclusive` — no reliable comparison could be established, so no
+ * drift claim is made in either direction; drift is never silently hidden:
+ * an old patch is never presented as current state.
+ */
+export declare function compareWorkspaceObservations(stored: WorkspaceStateRecord, fresh: WorkspaceStateRecord | undefined, options?: WorkspaceComparisonOptions): WorkspaceComparisonOutcome;
+/** Shape of a persisted comparison record, minus what the caller supplies. */
+export type WorkspaceComparisonFields = WorkspaceComparisonOutcome & {
+    comparedAt: string;
+    comparedToObservationId: string;
+    version: typeof WORKSPACE_RECORD_VERSION;
+};
+/** Build the record handed to appendWorkspaceComparison. */
+export declare function buildWorkspaceComparison(comparedToObservationId: string, outcome: WorkspaceComparisonOutcome, now?: () => string): WorkspaceStateComparison;
+//# sourceMappingURL=comparison.d.ts.map

package/dist/core/workspace/comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.d.ts","sourceRoot":"","sources":["../../../src/core/workspace/comparison.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAEtD,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,wBAAwB,EAAE,QAAQ,GAAG,cAAc,GAAG,UAAU,CAAC,CAAC;AAEhH,MAAM,WAAW,0BAA0B;IAC1C,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CAC/C;AAyCD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC3C,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,oBAAoB,GAAG,SAAS,EACvC,OAAO,GAAE,0BAA+B,GACtC,0BAA0B,CAyC5B;AAED,8EAA8E;AAC9E,MAAM,MAAM,yBAAyB,GAAG,0BAA0B,GAAG;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,MAAM,CAAC;IAChC,OAAO,EAAE,OAAO,wBAAwB,CAAC;CACzC,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,wBAAwB,CACvC,uBAAuB,EAAE,MAAM,EAC/B,OAAO,EAAE,0BAA0B,EACnC,GAAG,GAAE,MAAM,MAAuC,GAChD,wBAAwB,CAS1B","sourcesContent":["import { existsSync } from \"node:fs\";\nimport type { WorkspaceStateComparison, WorkspaceStateRecord } from \"./state.ts\";\nimport { WORKSPACE_RECORD_VERSION } from \"./state.ts\";\n\n/** Upper bound on `changedPaths` carried in one comparison record. */\nexport const MAX_CHANGED_PATHS = 200;\n\nexport type WorkspaceComparisonOutcome = Pick<WorkspaceStateComparison, \"result\" | \"changedPaths\" | \"warnings\">;\n\nexport interface WorkspaceComparisonOptions {\n\t/** Probe for stored patch artifacts; defaults to existence on disk. */\n\tartifactProbe?: (storePath: string) => boolean;\n}\n\nfunction pathTupleKey(path: {\n\tpath: string;\n\tkind: string;\n\tstaged?: boolean;\n\tunstaged?: boolean;\n\tignored?: boolean;\n\tcontentHash?: string;\n}): string {\n\treturn [\n\t\tpath.path,\n\t\tpath.kind,\n\t\tpath.staged ? \"s\" : \"\",\n\t\tpath.unstaged ? \"u\" : \"\",\n\t\tpath.ignored ? \"i\" : \"\",\n\t\tpath.contentHash ?? \"\",\n\t].join(\"\\u0000\");\n}\n\nfunction changedPathsBetween(stored: WorkspaceStateRecord, fresh: WorkspaceStateRecord, warnings: string[]): string[] {\n\tconst storedKeys = new Map<string, string>();\n\tfor (const p of stored.paths) storedKeys.set(p.path, pathTupleKey(p));\n\tconst freshKeys = new Map<string, string>();\n\tfor (const p of fresh.paths) freshKeys.set(p.path, pathTupleKey(p));\n\n\tconst changed = new Set<string>();\n\tfor (const [path, key] of storedKeys) {\n\t\tif (freshKeys.get(path) !== key) changed.add(path);\n\t}\n\tfor (const [path, key] of freshKeys) {\n\t\tif (storedKeys.get(path) !== key) changed.add(path);\n\t}\n\tconst sorted = [...changed].sort();\n\tif (sorted.length > MAX_CHANGED_PATHS) {\n\t\twarnings.push(`changed path list truncated at ${MAX_CHANGED_PATHS} of ${sorted.length} entries`);\n\t\treturn sorted.slice(0, MAX_CHANGED_PATHS);\n\t}\n\treturn sorted;\n}\n\n/**\n * WS.5: compare fresh workspace state against a stored observation (spec\n * 2026-09-01-harness-correctness-and-workspace-state.md § 3). Pure: same\n * inputs, same outcome. `unavailable` — the workspace could not be observed\n * now; `inconclusive` — no reliable comparison could be established, so no\n * drift claim is made in either direction; drift is never silently hidden:\n * an old patch is never presented as current state.\n */\nexport function compareWorkspaceObservations(\n\tstored: WorkspaceStateRecord,\n\tfresh: WorkspaceStateRecord | undefined,\n\toptions: WorkspaceComparisonOptions = {},\n): WorkspaceComparisonOutcome {\n\tconst warnings: string[] = [];\n\n\tif (!fresh || fresh.status === \"failed\" || fresh.status === \"unsupported\") {\n\t\treturn { result: \"unavailable\", warnings };\n\t}\n\tif (fresh.status === \"incomplete\") {\n\t\twarnings.push(\"fresh observation is incomplete; comparison is not reliable\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\tif (stored.status === \"incomplete\") {\n\t\twarnings.push(\"stored observation is incomplete; comparison is not reliable\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\tif (stored.status !== \"observed\") {\n\t\twarnings.push(\"stored observation has no comparable baseline\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\n\tconst storedBase = stored.base;\n\tconst freshBase = fresh.base;\n\tif (!storedBase?.worktreeDigest || !freshBase?.worktreeDigest) {\n\t\twarnings.push(\"worktree digest missing on one side; comparison is not reliable\");\n\t\treturn { result: \"inconclusive\", warnings };\n\t}\n\n\tconst sameIndex = (storedBase.indexDigest ?? \"\") === (freshBase.indexDigest ?? \"\");\n\tconst sameWorktree = storedBase.worktreeDigest === freshBase.worktreeDigest;\n\n\tif (stored.patchArtifactRef) {\n\t\tconst probe = options.artifactProbe ?? ((p: string) => existsSync(p));\n\t\tif (!probe(stored.patchArtifactRef.file)) {\n\t\t\twarnings.push(`stored workspace patch artifact ${stored.patchArtifactRef.artifactId} is missing on disk`);\n\t\t}\n\t}\n\n\tif (sameIndex && sameWorktree) {\n\t\treturn { result: \"same\", warnings };\n\t}\n\tconst changedPaths = changedPathsBetween(stored, fresh, warnings);\n\treturn { result: \"drifted\", changedPaths, warnings };\n}\n\n/** Shape of a persisted comparison record, minus what the caller supplies. */\nexport type WorkspaceComparisonFields = WorkspaceComparisonOutcome & {\n\tcomparedAt: string;\n\tcomparedToObservationId: string;\n\tversion: typeof WORKSPACE_RECORD_VERSION;\n};\n\n/** Build the record handed to appendWorkspaceComparison. */\nexport function buildWorkspaceComparison(\n\tcomparedToObservationId: string,\n\toutcome: WorkspaceComparisonOutcome,\n\tnow: () => string = () => new Date().toISOString(),\n): WorkspaceStateComparison {\n\treturn {\n\t\tversion: WORKSPACE_RECORD_VERSION,\n\t\tcomparedAt: now(),\n\t\tcomparedToObservationId,\n\t\tresult: outcome.result,\n\t\tchangedPaths: outcome.changedPaths,\n\t\twarnings: outcome.warnings,\n\t};\n}\n"]}