harnery 0.36.0 → 0.38.0

package/dist/core/hooks/health.d.ts

@@ -0,0 +1,59 @@
+import type { Adapter } from "../adapter.js";
+export declare const HOOK_HEALTH_EVENT: "agent_hook.completed";
+export declare const HOOK_HEALTH_RECEIPT_VERSION: 1;
+export declare const HOOK_HEALTH_ERROR_PHASE_LIMIT = 8;
+export type HookHealthOutcome = "completed" | "skipped" | "degraded" | "faulted";
+export interface HookHealthState {
+    readonly started_at_ms: number;
+    readonly started_rss_bytes: number;
+    readonly event_name: string | null;
+    readonly adapter: Adapter | null;
+    readonly payload_bytes: number;
+    coord_root: string | null;
+    owner_id?: string;
+    skipped_reason?: string;
+    v3_state?: string;
+    error_phases: string[];
+}
+export interface HookHealthReceipt {
+    receipt_version: typeof HOOK_HEALTH_RECEIPT_VERSION;
+    hook_name: string;
+    adapter: Adapter | "unknown";
+    outcome: HookHealthOutcome;
+    exit_contract: "always-zero";
+    exit_code: 0;
+    duration_ms: number;
+    payload_bytes: number;
+    pid: number;
+    rss_start_bytes: number;
+    rss_end_bytes: number;
+    rss_delta_bytes: number;
+    retry_worker: boolean;
+    error_count: number;
+    error_phases: readonly string[];
+    owner_id?: string;
+    skipped_reason?: string;
+    v3_state?: string;
+}
+export declare function beginHookHealth(input: {
+    started_at_ms: number;
+    started_rss_bytes: number;
+    event_name: string | null;
+    adapter: Adapter | null;
+    payload_bytes: number;
+}): HookHealthState;
+export declare function observeHookDebug(state: HookHealthState | undefined, entry: Readonly<Record<string, unknown>>): void;
+export declare function observeHookError(state: HookHealthState | undefined, phase: unknown): void;
+export declare function finalizeHookHealth(state: HookHealthState, input: {
+    finished_at_ms: number;
+    finished_rss_bytes: number;
+    pid: number;
+    faulted?: boolean;
+}): HookHealthReceipt;
+export declare function writeHookHealthCompletion(state: HookHealthState | undefined, input: {
+    finished_at_ms: number;
+    finished_rss_bytes: number;
+    pid: number;
+    faulted?: boolean;
+}): HookHealthReceipt | undefined;
+//# sourceMappingURL=health.d.ts.map

package/dist/core/hooks/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,eAAO,MAAM,iBAAiB,EAAG,sBAA+B,CAAC;AACjE,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAC;AACtD,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,OAAO,2BAA2B,CAAC;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,eAAe,CAMlB;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,IAAI,CAMN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGzF;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE;IACL,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,iBAAiB,CA+BnB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,KAAK,EAAE;IACL,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,iBAAiB,GAAG,SAAS,CAS/B"}

package/dist/core/hooks/health.js

@@ -0,0 +1,84 @@
+import { processLogger } from "../storage/logger.js";
+export const HOOK_HEALTH_EVENT = "agent_hook.completed";
+export const HOOK_HEALTH_RECEIPT_VERSION = 1;
+export const HOOK_HEALTH_ERROR_PHASE_LIMIT = 8;
+export function beginHookHealth(input) {
+    return {
+        ...input,
+        coord_root: null,
+        error_phases: [],
+    };
+}
+export function observeHookDebug(state, entry) {
+    if (!state)
+        return;
+    const skipped = safeToken(entry.skipped);
+    if (skipped)
+        state.skipped_reason = skipped;
+    const v3State = safeToken(entry.event_v3_state);
+    if (v3State)
+        state.v3_state = v3State;
+}
+export function observeHookError(state, phase) {
+    if (!state || state.error_phases.length >= HOOK_HEALTH_ERROR_PHASE_LIMIT)
+        return;
+    state.error_phases.push(safeToken(phase) ?? "unknown");
+}
+export function finalizeHookHealth(state, input) {
+    const duration = Math.max(0, Math.floor(input.finished_at_ms - state.started_at_ms));
+    const rssStart = boundedInteger(state.started_rss_bytes);
+    const rssEnd = boundedInteger(input.finished_rss_bytes);
+    const hookName = safeToken(state.event_name) ?? "unknown";
+    return {
+        receipt_version: HOOK_HEALTH_RECEIPT_VERSION,
+        hook_name: hookName,
+        adapter: state.adapter ?? "unknown",
+        outcome: input.faulted
+            ? "faulted"
+            : state.error_phases.length > 0
+                ? "degraded"
+                : state.skipped_reason
+                    ? "skipped"
+                    : "completed",
+        exit_contract: "always-zero",
+        exit_code: 0,
+        duration_ms: duration,
+        payload_bytes: boundedInteger(state.payload_bytes),
+        pid: boundedInteger(input.pid),
+        rss_start_bytes: rssStart,
+        rss_end_bytes: rssEnd,
+        rss_delta_bytes: rssEnd - rssStart,
+        retry_worker: hookName === "runtime-context-retry",
+        error_count: state.error_phases.length,
+        error_phases: [...state.error_phases],
+        ...(state.owner_id ? { owner_id: state.owner_id } : {}),
+        ...(state.skipped_reason ? { skipped_reason: state.skipped_reason } : {}),
+        ...(state.v3_state ? { v3_state: state.v3_state } : {}),
+    };
+}
+export function writeHookHealthCompletion(state, input) {
+    if (!state?.coord_root)
+        return undefined;
+    const receipt = finalizeHookHealth(state, input);
+    try {
+        processLogger(state.coord_root, "agent-hook").info(HOOK_HEALTH_EVENT, { ...receipt });
+    }
+    catch {
+        // Hook health is observer-only. Logging can never change adapter behavior.
+    }
+    return receipt;
+}
+function safeToken(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value
+        .trim()
+        .slice(0, 128)
+        .replace(/[^a-zA-Z0-9._:/+-]+/g, "-");
+    return /^[a-zA-Z0-9]/.test(normalized) ? normalized : undefined;
+}
+function boundedInteger(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(value)));
+}

package/dist/core/hooks/resolve/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,2BAA2B,wBAAc,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GACb,OAAO,CAiCT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,OAAO,CAKT;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,OAAO,CAIT;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CAAA;CAAE,CAAC;AAEpF;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,4BAA4B,CA0B9B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAUrF;AAwDD;4CAC4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,GAAG,SAAS,CA8BnC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAkDpB"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,2BAA2B,wBAAc,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GACb,OAAO,CAiCT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,OAAO,CAKT;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,OAAO,CAIT;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CAAA;CAAE,CAAC;AAEpF;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/D,4BAA4B,CAiC9B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAUrF;AAwDD;4CAC4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,qBAAqB,GAAG,SAAS,CA8BnC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAkDpB"}

package/dist/core/hooks/resolve/transcript.js

@@ -154,9 +154,16 @@ export function inspectSessionNameDisplayImmediately(transcriptPath, name, start
             awaitingReply = false;
         }
     }
-    return sawMintResult && awaitingReply
-        ? { state: "unavailable", reason: "transcript_not_ready" }
-        : { state: "absent" };
+    // Some adapter transcripts persist assistant messages and tool requests but
+    // omit tool-result rows entirely. A readable file with no mint result cannot
+    // establish the ordered verification boundary, so it is unavailable evidence
+    // rather than proof that the agent displayed the title incorrectly. Only a
+    // transcript that contains the mint followed by a non-matching assistant
+    // reply can safely deny the next tool.
+    if (!sawMintResult || awaitingReply) {
+        return { state: "unavailable", reason: "transcript_not_ready" };
+    }
+    return { state: "absent" };
 }
 /**
  * Resolve a transcript path at the adapter boundary. Windows-native Codex can

package/dist/core/hooks/session-name-presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-name-presence.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/session-name-presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAC3C,mBAAmB,CAcrB"}
+{"version":3,"file":"session-name-presence.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/session-name-presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAC3C,mBAAmB,CAkBrB"}

package/dist/core/hooks/session-name-presence.js

@@ -21,6 +21,7 @@
  *
  * Never throws: coordination telemetry must not take down a hook.
  */
+import { sessionNameDisplayAcceptedNames } from "../agents/session-name-display.js";
 import { stampSessionNameSeen } from "../agents/state/heartbeat-writer.js";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
 export function sessionNamePresence(coordRoot, instanceId, scanAssistantText) {
@@ -32,7 +33,9 @@ export function sessionNamePresence(coordRoot, instanceId, scanAssistantText) {
         if (row?.session_name_seen_for === name) {
             return { session_name_present: true, session_name_present_for: name };
         }
-        const present = scanAssistantText(name);
+        // A display of the title Harnery last asked for counts here too, so Stop
+        // and the PreToolUse gate cannot disagree about the same reply.
+        const present = sessionNameDisplayAcceptedNames(row).some((candidate) => scanAssistantText(candidate));
         if (present)
             stampSessionNameSeen(coordRoot, instanceId, name);
         return { session_name_present: present, session_name_present_for: name };

package/dist/core/qa-artifacts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Managed output workspaces for page-QA commands.
+ *
+ * An implicit qa-run/qa-record output is working evidence, not project source.
+ * Keep it in the bounded artifact store. Callers that pass --out-dir retain
+ * full control of that explicit destination.
+ */
+import type { HarneryProgramContext } from "../commander.js";
+export type QaArtifactKind = "qa-run" | "qa-record" | "review-pack";
+export declare function resolveQaRepoRoot(context?: HarneryProgramContext): string;
+export declare function createManagedQaOutParent(repoRoot: string, kind: QaArtifactKind, opts?: {
+    retentionMinutes?: number;
+}): string;
+/**
+ * Find the newest run in a valid managed QA workspace. This keeps no-path
+ * `qa-status` useful even though every implicit invocation gets an isolated
+ * artifact workspace instead of sharing one root-level `.qa-run` directory.
+ */
+export declare function latestManagedQaRun(repoRoot: string): string | null;
+//# sourceMappingURL=qa-artifacts.d.ts.map

package/dist/core/qa-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qa-artifacts.d.ts","sourceRoot":"","sources":["../../src/core/qa-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAW7D,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAEpE,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAEzE;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,MAAM,CAcR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuClE"}

package/dist/core/qa-artifacts.js

@@ -0,0 +1,110 @@
+/**
+ * Managed output workspaces for page-QA commands.
+ *
+ * An implicit qa-run/qa-record output is working evidence, not project source.
+ * Keep it in the bounded artifact store. Callers that pass --out-dir retain
+ * full control of that explicit destination.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { monorepoRoot } from "./agents/index.js";
+import { ARTIFACT_MANIFEST, artifactsRoot, configuredArtifactRetentionDays, createArtifact, parseArtifactManifest, } from "./artifacts/index.js";
+export function resolveQaRepoRoot(context) {
+    return resolve(context?.repoRoot ?? monorepoRoot() ?? process.cwd());
+}
+export function createManagedQaOutParent(repoRoot, kind, opts = {}) {
+    return createArtifact(repoRoot, {
+        slug: kind,
+        purpose: kind === "qa-run"
+            ? "Page QA run evidence"
+            : kind === "review-pack"
+                ? "Page review pack"
+                : "Hand-recorded page QA evidence",
+        retentionDays: configuredArtifactRetentionDays(repoRoot),
+        // A standalone review-pack workspace IS the pack, so the artifact store's
+        // own expiry follows the pack's (90 minutes by default, ruled 2026-09-02).
+        ...(opts.retentionMinutes !== undefined ? { retentionMinutes: opts.retentionMinutes } : {}),
+    }).path;
+}
+/**
+ * Find the newest run in a valid managed QA workspace. This keeps no-path
+ * `qa-status` useful even though every implicit invocation gets an isolated
+ * artifact workspace instead of sharing one root-level `.qa-run` directory.
+ */
+export function latestManagedQaRun(repoRoot) {
+    const root = artifactsRoot(repoRoot);
+    if (!existsSync(root))
+        return null;
+    let workspaceNames;
+    try {
+        workspaceNames = readdirSync(root).sort();
+    }
+    catch {
+        return null;
+    }
+    let latest = null;
+    for (const workspaceName of workspaceNames) {
+        const workspace = join(root, workspaceName);
+        const manifest = readQaManifest(join(workspace, ARTIFACT_MANIFEST));
+        if (!manifest)
+            continue;
+        let runNames;
+        try {
+            runNames = readdirSync(workspace)
+                .filter((name) => name.startsWith("run-"))
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const runName of runNames) {
+            const runDir = join(workspace, runName);
+            const startedAtMs = readStartedAtMs(runDir);
+            if (startedAtMs === null)
+                continue;
+            if (latest === null ||
+                startedAtMs > latest.startedAtMs ||
+                (startedAtMs === latest.startedAtMs && runDir > latest.path)) {
+                latest = { path: runDir, startedAtMs };
+            }
+        }
+    }
+    return latest?.path ?? null;
+}
+function readQaManifest(path) {
+    try {
+        const parsed = parseArtifactManifest(JSON.parse(readFileSync(path, "utf8")));
+        if (!parsed.ok)
+            return null;
+        if (parsed.manifest.slug !== "qa-run" && parsed.manifest.slug !== "qa-record")
+            return null;
+        return parsed.manifest;
+    }
+    catch {
+        return null;
+    }
+}
+function readStartedAtMs(runDir) {
+    for (const file of ["run-status.json", "page-qa-result.json"]) {
+        try {
+            const value = JSON.parse(readFileSync(join(runDir, file), "utf8"));
+            const run = value.run;
+            const startedAt = typeof value.started_at === "string"
+                ? value.started_at
+                : run &&
+                    typeof run === "object" &&
+                    typeof run.started_at === "string"
+                    ? run.started_at
+                    : null;
+            if (!startedAt)
+                continue;
+            const parsed = Date.parse(startedAt);
+            if (!Number.isNaN(parsed))
+                return parsed;
+        }
+        catch {
+            // Try the other authoritative run document.
+        }
+    }
+    return null;
+}

package/dist/core/resources/contract.d.ts

@@ -0,0 +1,96 @@
+export declare const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export declare const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;
+export type ResourceSupportState = "supported" | "partial" | "unsupported" | "error";
+export interface ResourceProcessSample {
+    pid: number;
+    ppid: number;
+    start_id: string;
+    state: string;
+    name: string;
+    command: string;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    age_seconds: number;
+    owner_kind: "agent" | "service" | "unattributed";
+    owner_id: string | null;
+    owner_root_pid: number | null;
+    owner_source?: "pid-map" | "session-environment" | "service";
+}
+export interface ResourceProcessGroup {
+    kind: ResourceProcessSample["owner_kind"];
+    id: string;
+    process_count: number;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    root_pids: number[];
+}
+export interface ResourceMachineSample {
+    cpu_percent: number | null;
+    cpu_logical_count: number;
+    load_average: [number, number, number] | null;
+    memory_total_bytes: number | null;
+    memory_available_bytes: number | null;
+    memory_used_bytes: number | null;
+    memory_percent: number | null;
+    swap_total_bytes: number | null;
+    swap_used_bytes: number | null;
+    process_count: number;
+}
+export interface ResourceSnapshot {
+    schema_version: typeof RESOURCE_SNAPSHOT_SCHEMA_VERSION;
+    sampled_at: string;
+    interval_ms: number | null;
+    sample_duration_ms: number;
+    collector_cpu_ms: number;
+    platform: NodeJS.Platform;
+    namespace: "host" | "wsl" | "unknown";
+    support: {
+        state: ResourceSupportState;
+        sampler: "procfs" | "unsupported";
+        reason?: string;
+    };
+    machine: ResourceMachineSample;
+    groups: ResourceProcessGroup[];
+    processes: ResourceProcessSample[];
+    visible_process_count: number;
+    omitted_process_count: number;
+    unattributed_process_count: number;
+}
+export interface ResourceServiceStatusRecord {
+    schema_version: typeof RESOURCE_SERVICE_STATUS_SCHEMA_VERSION;
+    pid: number;
+    start_token?: string;
+    host: string;
+    nonce: string;
+    state: "starting" | "running" | "stopping" | "stopped" | "error";
+    started_at: string;
+    heartbeat_at: string;
+    stopped_at?: string;
+    interval_ms: number;
+    sample_count: number;
+    last_sample_at?: string;
+    last_error_code?: string;
+}
+export interface ResourceServiceStatus {
+    running: boolean;
+    stale: boolean;
+    record?: ResourceServiceStatusRecord;
+    status_path: string;
+    snapshot_path: string;
+}
+export interface ResourceSamplerState {
+    sampled_at_ms: number;
+    cpu_total_ticks: number;
+    cpu_idle_ticks: number;
+    process_ticks: Map<string, number>;
+    process_owners: Map<string, ResourceProcessOwnerProof>;
+}
+export interface ResourceProcessOwnerProof {
+    session_id: string;
+    instance_id: string;
+}
+export interface ResourceSampleResult {
+    snapshot: ResourceSnapshot;
+    state?: ResourceSamplerState;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/resources/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/resources/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/resources/contract.js

@@ -0,0 +1,2 @@
+export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;

package/dist/core/resources/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contract.js";
+export * from "./sampler.js";
+export * from "./service.js";
+export * from "./service-status.js";
+export * from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/resources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/resources/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/core/resources/index.js

@@ -0,0 +1,5 @@
+export * from "./contract.js";
+export * from "./sampler.js";
+export * from "./service.js";
+export * from "./service-status.js";
+export * from "./storage.js";

package/dist/core/resources/sampler.d.ts

@@ -0,0 +1,34 @@
+import { type ResourceSampleResult, type ResourceSamplerState } from "./contract.js";
+interface ResourceSamplerOptions {
+    procRoot?: string;
+    nowMs?: number;
+    clockTicks?: number;
+    pageSize?: number;
+    services?: readonly {
+        pid: number;
+        id: string;
+    }[];
+    sessionOwners?: readonly SessionOwner[];
+    unattributedCpuFloor?: number;
+    unattributedRssFloor?: number;
+    maxProcesses?: number;
+}
+interface SessionOwner {
+    nativeSessionId: string;
+    instanceId: string;
+    platform: string;
+    kind: string;
+}
+export declare function sampleResources(coordRoot: string, previous?: ResourceSamplerState, options?: ResourceSamplerOptions): ResourceSampleResult;
+export declare function parseLinuxProcessStat(line: string): {
+    pid: number;
+    name: string;
+    state: string;
+    ppid: number;
+    ticks: number;
+    startTicks: number;
+    rssPages: number;
+} | null;
+export declare function redactCommand(args: readonly string[]): string;
+export {};
+//# sourceMappingURL=sampler.d.ts.map

package/dist/core/resources/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../../src/core/resources/sampler.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AA0BvB,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,YAAY;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAKD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,oBAAoB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CAmJtB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CA0BP;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAuB7D"}