@webpieces/rules-config 0.4.709 → 0.4.711

package/src/harness-agent-activity.d.ts

@@ -0,0 +1,152 @@
+/**
+ * THE ONE PLACE THAT KNOWS ANYTHING ABOUT CLAUDE CODE'S ON-DISK STATE.
+ *
+ * ─── THE RULE THIS CLASS EXISTS UNDER ────────────────────────────────────────────────────────────
+ *
+ *      HARNESS STATE MAY ONLY VETO A REAP. IT MAY NEVER LICENSE ONE.
+ *
+ * Read that before reading anything else here, because every answer below is shaped by it. The
+ * licence to remove a worktree comes SOLELY from evidence wp-cleanup already computes and already
+ * gets right: a merged PR, a snapshot of a ref that still holds the work, a ref identical to
+ * origin/main, plus a clean `git status --porcelain`. This class answers ONE question — "is somebody
+ * plausibly still in there?" — and its only power is to STOP a reap that the branch evidence had
+ * already authorised. No answer it can give turns a spared worktree into a reaped one.
+ *
+ * ─── WHY IT EXISTS ───────────────────────────────────────────────────────────────────────────────
+ * `git worktree lock` reasons written by the Claude Code harness carry a pid, and wp-cleanup used to
+ * ask the kernel whether that pid was alive. It always is. Subagents are NOT separate OS processes —
+ * every agent in a session records the SAME pid, the session process — so "is that pid running?"
+ * reduced to "is the editor still open?", which is true by construction for the whole life of a
+ * session. Observed in monorepo-nx2: nine worktrees against a cap of five, eight of them reported as
+ * "that agent is working in here" with one identical pid, exactly ONE agent actually running, and
+ * several of the others' PRs already merged.
+ *
+ * So a veto has to come from somewhere that knows about AGENTS rather than processes. The harness
+ * does, and it writes it down:
+ *
+ *     <config>/projects/<project-slug>/<sessionId>/subagents/agent-<id>.meta.json
+ *     <config>/projects/<project-slug>/<sessionId>/subagents/agent-<id>.jsonl
+ *
+ * `<config>` is `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`. `agent-<id>` is ONE token, and it is
+ * the same token in three places: the stem of those two filenames, the basename of the `worktreePath`
+ * that meta records, and the name in the lock reason `claude agent agent-<id> (pid N …)`. So worktree
+ * → agent state is an exact lookup, not a heuristic — and nothing here re-derives or re-prefixes that
+ * token, because a filename built from half of it is how a lookup quietly becomes a miss.
+ *
+ * ─── THE SIGNAL: THE SHAPE OF THE LAST RECORD IN THE AGENT'S OWN TRANSCRIPT ──────────────────────
+ * An agent's loop pauses when the model emits text and asks for no tool. That is the definition of
+ * the loop, not a correlation with one:
+ *
+ *   last record is `assistant` with NO `tool_use` block  →  RETURNED — not currently in a tool loop
+ *   anything else (a `tool_use` block, a `user`/tool_result record)  →  MID-LOOP
+ *
+ * Verified on three agents known to have finished (all `assistant` / `['text']`) and on a live one
+ * (`assistant` / `['tool_use']`). `thinking` blocks appear alongside `text` and change nothing: the
+ * criterion is the ABSENCE of `tool_use`, never "exactly one block". A `user` record's content can be
+ * a plain STRING rather than a list of blocks; that is mid-loop too, and must not throw.
+ *
+ * ─── "RETURNED" IS NOT "DONE FOREVER", WHICH IS WHY IT CANNOT LICENSE A REAP ──────────────────────
+ * Measured: a throwaway agent returned with a text-only record at 17:04:20, and at 17:08:11 a `user`
+ * record appeared and it ran again, returning a second time at 17:08:13. The harness RE-INVOKES an
+ * agent when a background child it started completes, and when a parent sends it a message. It holds
+ * its worktree across that gap. So RETURNED means "not in a tool loop right now" and nothing
+ * stronger — which is survivable only because of the rule at the top of this file: the reap was
+ * already authorised by a merged PR and a clean tree, and an agent that briefly resumes into that
+ * situation has nothing to lose.
+ *
+ * ─── WHY MTIME IS ONLY A TIEBREAKER ──────────────────────────────────────────────────────────────
+ * Freshness of the transcript looks like the obvious liveness signal and is NOT one. Measured: one
+ * minute after that throwaway agent finished, its mtime was FRESHER than the genuinely live agent's
+ * had been moments earlier. And a live agent writes nothing at all while it sits inside one long Bash
+ * call — a `wp-build` is ten minutes of silence — so any threshold safe against that also covers
+ * every just-finished agent, which is precisely the population wp-cleanup meets. Mtime alone does not
+ * fix this bug; it re-times it. It earns its place on exactly one case: telling a mid-loop transcript
+ * that is being written RIGHT NOW (a live agent, veto) from one frozen mid-`tool_use` by a killed
+ * session (no veto — that is the original "looks live forever" defect).
+ *
+ * ─── NEGATIVE RESULT — DO NOT RE-TRY THIS ────────────────────────────────────────────────────────
+ * The meta records a `toolUseId`, and a `tool_result` for it in the SPAWNER's transcript looks like an
+ * exact completion marker. It is NOT one: a backgrounded Agent call gets its "launched successfully"
+ * tool_result IMMEDIATELY, so a running agent already has one, indistinguishable from a finished
+ * agent's. Measured on a live agent and rejected.
+ *
+ * ─── EVERY ANSWER FAILS SAFE ─────────────────────────────────────────────────────────────────────
+ * A missing config dir, an unreadable file, a meta describing a different worktree, a truncated last
+ * line — all of them are UNKNOWN. UNKNOWN withholds the veto, which is only ever safe because the
+ * branch evidence had to authorise the reap first.
+ *
+ * THIS IS UNDOCUMENTED HARNESS INTERNALS, deliberately quarantined in one file so a layout change
+ * breaks exactly here and degrades to "cannot tell" everywhere else.
+ */
+/** Mid-loop and being written to right now. The ONE answer that vetoes a reap. */
+export declare const AGENT_ACTIVITY_LIVE = "live";
+/** Its transcript ends with the model returning — not in a tool loop. It may still resume. */
+export declare const AGENT_ACTIVITY_RETURNED = "returned";
+/** No usable evidence, or a mid-loop transcript nobody has touched for a long time. */
+export declare const AGENT_ACTIVITY_UNKNOWN = "unknown";
+/**
+ * How long a MID-LOOP transcript may sit untouched before its silence stops vetoing a reap.
+ *
+ * Consulted for a mid-loop transcript only — a returned one is recognised by shape, whatever its
+ * mtime — so this number decides exactly one thing: how long an agent that was KILLED inside a tool
+ * call goes on vetoing. Generous on purpose, because a live agent writes NOTHING while it is inside
+ * one long Bash call and a `wp-build` or `nx run … :ci` is routinely ten minutes of that. A threshold
+ * in seconds would drop the veto on a building agent, which is the one direction that costs work;
+ * being late costs a directory the next cleanup takes.
+ */
+export declare const AGENT_TRANSCRIPT_QUIET_MS: number;
+export declare class AgentActivity {
+    /** One of the AGENT_ACTIVITY_* constants. */
+    state: string;
+    /** Human-readable evidence, printed verbatim into wp-cleanup's spared/overridden reasons. */
+    detail: string;
+    constructor(state: string, detail: string);
+}
+export declare class HarnessAgentActivityReader {
+    /**
+     * What the harness says about `agentId`, cross-checked against the worktree we are judging.
+     *
+     * `worktreePath` is not decoration: it is what makes this a LOOKUP rather than a guess. If the
+     * meta we find records a different worktree we have matched the wrong thing, and the answer is
+     * UNKNOWN — never an answer about somebody else's directory.
+     */
+    activityOf(agentId: string, worktreePath: string, now?: number): AgentActivity;
+    /**
+     * Did the agent RETURN? True only for an `assistant` record whose content asks for no tool.
+     *
+     * A `user` record (a tool result coming back, or a message sent to the agent) is mid-loop by
+     * definition — and its content may be a plain string, which is why the array check comes first. So
+     * is an `assistant` record carrying a `tool_use` EVEN ALONGSIDE TEXT: the model narrating before
+     * it calls something is not a return.
+     */
+    private isReturn;
+    /**
+     * The agent's own transcript, or the reason there is none — each of the three exits phrased for
+     * what actually happened. `exists` is asked BEFORE `readMeta` precisely so "not there" and
+     * "there and unreadable" stay distinguishable; folding them together is what produced the flat
+     * over-claim this replaced.
+     */
+    private locate;
+    /** Every `<config>/projects/<slug>/<session>/subagents` directory that exists right now. */
+    private subagentDirs;
+    /**
+     * Seam: where the harness keeps its per-project state. `$CLAUDE_CONFIG_DIR` wins when set, which
+     * is how the harness itself resolves it; specs override this to point at a fixture tree.
+     */
+    protected projectsRoot(): string;
+    private minutesAgo;
+    private exists;
+    private readMeta;
+    /**
+     * The last complete JSONL record of `transcript`, or null.
+     *
+     * Reads only the tail, because these files grow without bound and only the final line matters. A
+     * window that starts mid-record yields an unparseable fragment and therefore null — "cannot tell"
+     * — which is exactly what a truncated or half-written last line should also produce.
+     */
+    private lastRecord;
+    private readTail;
+    private readDir;
+    private isDirectory;
+    private mtimeOf;
+}

package/src/harness-agent-activity.js

@@ -0,0 +1,345 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HarnessAgentActivityReader = exports.AgentActivity = exports.AGENT_TRANSCRIPT_QUIET_MS = exports.AGENT_ACTIVITY_UNKNOWN = exports.AGENT_ACTIVITY_RETURNED = exports.AGENT_ACTIVITY_LIVE = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+const inversify_1 = require("inversify");
+const to_error_1 = require("./to-error");
+/**
+ * THE ONE PLACE THAT KNOWS ANYTHING ABOUT CLAUDE CODE'S ON-DISK STATE.
+ *
+ * ─── THE RULE THIS CLASS EXISTS UNDER ────────────────────────────────────────────────────────────
+ *
+ *      HARNESS STATE MAY ONLY VETO A REAP. IT MAY NEVER LICENSE ONE.
+ *
+ * Read that before reading anything else here, because every answer below is shaped by it. The
+ * licence to remove a worktree comes SOLELY from evidence wp-cleanup already computes and already
+ * gets right: a merged PR, a snapshot of a ref that still holds the work, a ref identical to
+ * origin/main, plus a clean `git status --porcelain`. This class answers ONE question — "is somebody
+ * plausibly still in there?" — and its only power is to STOP a reap that the branch evidence had
+ * already authorised. No answer it can give turns a spared worktree into a reaped one.
+ *
+ * ─── WHY IT EXISTS ───────────────────────────────────────────────────────────────────────────────
+ * `git worktree lock` reasons written by the Claude Code harness carry a pid, and wp-cleanup used to
+ * ask the kernel whether that pid was alive. It always is. Subagents are NOT separate OS processes —
+ * every agent in a session records the SAME pid, the session process — so "is that pid running?"
+ * reduced to "is the editor still open?", which is true by construction for the whole life of a
+ * session. Observed in monorepo-nx2: nine worktrees against a cap of five, eight of them reported as
+ * "that agent is working in here" with one identical pid, exactly ONE agent actually running, and
+ * several of the others' PRs already merged.
+ *
+ * So a veto has to come from somewhere that knows about AGENTS rather than processes. The harness
+ * does, and it writes it down:
+ *
+ *     <config>/projects/<project-slug>/<sessionId>/subagents/agent-<id>.meta.json
+ *     <config>/projects/<project-slug>/<sessionId>/subagents/agent-<id>.jsonl
+ *
+ * `<config>` is `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`. `agent-<id>` is ONE token, and it is
+ * the same token in three places: the stem of those two filenames, the basename of the `worktreePath`
+ * that meta records, and the name in the lock reason `claude agent agent-<id> (pid N …)`. So worktree
+ * → agent state is an exact lookup, not a heuristic — and nothing here re-derives or re-prefixes that
+ * token, because a filename built from half of it is how a lookup quietly becomes a miss.
+ *
+ * ─── THE SIGNAL: THE SHAPE OF THE LAST RECORD IN THE AGENT'S OWN TRANSCRIPT ──────────────────────
+ * An agent's loop pauses when the model emits text and asks for no tool. That is the definition of
+ * the loop, not a correlation with one:
+ *
+ *   last record is `assistant` with NO `tool_use` block  →  RETURNED — not currently in a tool loop
+ *   anything else (a `tool_use` block, a `user`/tool_result record)  →  MID-LOOP
+ *
+ * Verified on three agents known to have finished (all `assistant` / `['text']`) and on a live one
+ * (`assistant` / `['tool_use']`). `thinking` blocks appear alongside `text` and change nothing: the
+ * criterion is the ABSENCE of `tool_use`, never "exactly one block". A `user` record's content can be
+ * a plain STRING rather than a list of blocks; that is mid-loop too, and must not throw.
+ *
+ * ─── "RETURNED" IS NOT "DONE FOREVER", WHICH IS WHY IT CANNOT LICENSE A REAP ──────────────────────
+ * Measured: a throwaway agent returned with a text-only record at 17:04:20, and at 17:08:11 a `user`
+ * record appeared and it ran again, returning a second time at 17:08:13. The harness RE-INVOKES an
+ * agent when a background child it started completes, and when a parent sends it a message. It holds
+ * its worktree across that gap. So RETURNED means "not in a tool loop right now" and nothing
+ * stronger — which is survivable only because of the rule at the top of this file: the reap was
+ * already authorised by a merged PR and a clean tree, and an agent that briefly resumes into that
+ * situation has nothing to lose.
+ *
+ * ─── WHY MTIME IS ONLY A TIEBREAKER ──────────────────────────────────────────────────────────────
+ * Freshness of the transcript looks like the obvious liveness signal and is NOT one. Measured: one
+ * minute after that throwaway agent finished, its mtime was FRESHER than the genuinely live agent's
+ * had been moments earlier. And a live agent writes nothing at all while it sits inside one long Bash
+ * call — a `wp-build` is ten minutes of silence — so any threshold safe against that also covers
+ * every just-finished agent, which is precisely the population wp-cleanup meets. Mtime alone does not
+ * fix this bug; it re-times it. It earns its place on exactly one case: telling a mid-loop transcript
+ * that is being written RIGHT NOW (a live agent, veto) from one frozen mid-`tool_use` by a killed
+ * session (no veto — that is the original "looks live forever" defect).
+ *
+ * ─── NEGATIVE RESULT — DO NOT RE-TRY THIS ────────────────────────────────────────────────────────
+ * The meta records a `toolUseId`, and a `tool_result` for it in the SPAWNER's transcript looks like an
+ * exact completion marker. It is NOT one: a backgrounded Agent call gets its "launched successfully"
+ * tool_result IMMEDIATELY, so a running agent already has one, indistinguishable from a finished
+ * agent's. Measured on a live agent and rejected.
+ *
+ * ─── EVERY ANSWER FAILS SAFE ─────────────────────────────────────────────────────────────────────
+ * A missing config dir, an unreadable file, a meta describing a different worktree, a truncated last
+ * line — all of them are UNKNOWN. UNKNOWN withholds the veto, which is only ever safe because the
+ * branch evidence had to authorise the reap first.
+ *
+ * THIS IS UNDOCUMENTED HARNESS INTERNALS, deliberately quarantined in one file so a layout change
+ * breaks exactly here and degrades to "cannot tell" everywhere else.
+ */
+/** Mid-loop and being written to right now. The ONE answer that vetoes a reap. */
+exports.AGENT_ACTIVITY_LIVE = 'live';
+/** Its transcript ends with the model returning — not in a tool loop. It may still resume. */
+exports.AGENT_ACTIVITY_RETURNED = 'returned';
+/** No usable evidence, or a mid-loop transcript nobody has touched for a long time. */
+exports.AGENT_ACTIVITY_UNKNOWN = 'unknown';
+/**
+ * How long a MID-LOOP transcript may sit untouched before its silence stops vetoing a reap.
+ *
+ * Consulted for a mid-loop transcript only — a returned one is recognised by shape, whatever its
+ * mtime — so this number decides exactly one thing: how long an agent that was KILLED inside a tool
+ * call goes on vetoing. Generous on purpose, because a live agent writes NOTHING while it is inside
+ * one long Bash call and a `wp-build` or `nx run … :ci` is routinely ten minutes of that. A threshold
+ * in seconds would drop the veto on a building agent, which is the one direction that costs work;
+ * being late costs a directory the next cleanup takes.
+ */
+exports.AGENT_TRANSCRIPT_QUIET_MS = 45 * 60 * 1000;
+/**
+ * How much of the tail of a transcript is read to find its last record.
+ *
+ * Transcripts are append-only and reach tens of megabytes; the answer lives in the final line. Large
+ * enough that a single fat record (a big tool result) still fits whole — and when it does not, the
+ * fragment fails to parse and the answer is UNKNOWN.
+ */
+const TRANSCRIPT_TAIL_BYTES = 8 * 1024 * 1024;
+// Data-only (per CLAUDE.md, classes for data). What the harness says about one agent, and why.
+class AgentActivity {
+    /** One of the AGENT_ACTIVITY_* constants. */
+    state;
+    /** Human-readable evidence, printed verbatim into wp-cleanup's spared/overridden reasons. */
+    detail;
+    constructor(state, detail) {
+        this.state = state;
+        this.detail = detail;
+    }
+}
+exports.AgentActivity = AgentActivity;
+/**
+ * Data-only. Where an agent's transcript is — or, when it is nowhere, WHICH of the three genuinely
+ * different silences we hit.
+ *
+ * One flat "no state file for that agent id" covered all three, and two of them were untrue: a meta
+ * that exists and cannot be PARSED, and a meta that exists and describes SOMEBODY ELSE'S worktree.
+ * That string is printed verbatim into wp-cleanup's reason, so it is a message asserting more than
+ * the evidence supports — the exact defect this whole file exists to remove, small and on the safe
+ * side but the same shape.
+ */
+class AgentStateLookup {
+    /** The agent's own transcript, or '' when there is none to read. */
+    transcript;
+    /** When `transcript` is '': the honest reason, printed to a human as-is. */
+    detail;
+    constructor(transcript, detail) {
+        this.transcript = transcript;
+        this.detail = detail;
+    }
+}
+let HarnessAgentActivityReader = class HarnessAgentActivityReader {
+    /**
+     * What the harness says about `agentId`, cross-checked against the worktree we are judging.
+     *
+     * `worktreePath` is not decoration: it is what makes this a LOOKUP rather than a guess. If the
+     * meta we find records a different worktree we have matched the wrong thing, and the answer is
+     * UNKNOWN — never an answer about somebody else's directory.
+     */
+    activityOf(agentId, worktreePath, now = Date.now()) {
+        const found = this.locate(agentId, worktreePath);
+        if (found.transcript === '')
+            return new AgentActivity(exports.AGENT_ACTIVITY_UNKNOWN, found.detail);
+        const last = this.lastRecord(found.transcript);
+        if (last === null) {
+            return new AgentActivity(exports.AGENT_ACTIVITY_UNKNOWN, 'its transcript could not be read to the end');
+        }
+        if (this.isReturn(last)) {
+            return new AgentActivity(exports.AGENT_ACTIVITY_RETURNED, 'its transcript ends with that agent returning its answer, so it is not in a tool call');
+        }
+        const written = this.mtimeOf(found.transcript);
+        if (written > 0 && now - written < exports.AGENT_TRANSCRIPT_QUIET_MS) {
+            return new AgentActivity(exports.AGENT_ACTIVITY_LIVE, `its transcript ends mid-tool-call and was written ${this.minutesAgo(now, written)}`);
+        }
+        return new AgentActivity(exports.AGENT_ACTIVITY_UNKNOWN, 'its transcript ends mid-tool-call but nothing has written to it for a long time, so that '
+            + 'agent was more likely killed than working');
+    }
+    /**
+     * Did the agent RETURN? True only for an `assistant` record whose content asks for no tool.
+     *
+     * A `user` record (a tool result coming back, or a message sent to the agent) is mid-loop by
+     * definition — and its content may be a plain string, which is why the array check comes first. So
+     * is an `assistant` record carrying a `tool_use` EVEN ALONGSIDE TEXT: the model narrating before
+     * it calls something is not a return.
+     */
+    isReturn(record) {
+        if ((record.type ?? '') !== 'assistant')
+            return false;
+        const content = record.message === undefined ? undefined : record.message.content;
+        if (!Array.isArray(content) || content.length === 0)
+            return false;
+        for (const block of content) {
+            if ((block.type ?? '') === 'tool_use')
+                return false;
+        }
+        return true;
+    }
+    /**
+     * The agent's own transcript, or the reason there is none — each of the three exits phrased for
+     * what actually happened. `exists` is asked BEFORE `readMeta` precisely so "not there" and
+     * "there and unreadable" stay distinguishable; folding them together is what produced the flat
+     * over-claim this replaced.
+     */
+    locate(agentId, worktreePath) {
+        for (const subagents of this.subagentDirs()) {
+            const metaPath = path.join(subagents, `${agentId}.meta.json`);
+            if (!this.exists(metaPath))
+                continue;
+            const meta = this.readMeta(metaPath);
+            if (meta === null) {
+                return new AgentStateLookup('', `that agent's harness state file (${metaPath}) could not be read`);
+            }
+            const recorded = meta.worktreePath ?? '';
+            if (recorded !== '' && worktreePath !== '' && path.resolve(recorded) !== path.resolve(worktreePath)) {
+                return new AgentStateLookup('', `the harness records that agent against a different worktree (${recorded})`);
+            }
+            return new AgentStateLookup(path.join(subagents, `${agentId}.jsonl`), '');
+        }
+        return new AgentStateLookup('', 'the Claude Code harness has no state file for that agent id');
+    }
+    /** Every `<config>/projects/<slug>/<session>/subagents` directory that exists right now. */
+    subagentDirs() {
+        const out = [];
+        const root = this.projectsRoot();
+        for (const project of this.readDir(root)) {
+            const projectDir = path.join(root, project);
+            for (const session of this.readDir(projectDir)) {
+                const subagents = path.join(projectDir, session, 'subagents');
+                if (this.isDirectory(subagents))
+                    out.push(subagents);
+            }
+        }
+        return out;
+    }
+    /**
+     * Seam: where the harness keeps its per-project state. `$CLAUDE_CONFIG_DIR` wins when set, which
+     * is how the harness itself resolves it; specs override this to point at a fixture tree.
+     */
+    projectsRoot() {
+        const configured = process.env['CLAUDE_CONFIG_DIR'] ?? '';
+        const root = configured !== '' ? configured : path.join(os.homedir(), '.claude');
+        return path.join(root, 'projects');
+    }
+    minutesAgo(now, written) {
+        const minutes = Math.max(0, Math.floor((now - written) / 60000));
+        return minutes === 1 ? '1 minute ago' : `${String(minutes)} minutes ago`;
+    }
+    // ── Everything below is a guarded filesystem read: any failure is silence, never a throw. ──
+    exists(filePath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.existsSync(filePath);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return false;
+        }
+    }
+    // null means "it is there and this release could not make sense of it" — NOT "it is absent".
+    readMeta(metaPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
+    /**
+     * The last complete JSONL record of `transcript`, or null.
+     *
+     * Reads only the tail, because these files grow without bound and only the final line matters. A
+     * window that starts mid-record yields an unparseable fragment and therefore null — "cannot tell"
+     * — which is exactly what a truncated or half-written last line should also produce.
+     */
+    lastRecord(transcript) {
+        const lines = this.readTail(transcript).split('\n')
+            .filter((line) => line.trim() !== '');
+        if (lines.length === 0)
+            return null;
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return JSON.parse(lines[lines.length - 1]);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
+    readTail(filePath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const size = fs.statSync(filePath).size;
+            const length = Math.min(size, TRANSCRIPT_TAIL_BYTES);
+            const buffer = Buffer.alloc(length);
+            const fd = fs.openSync(filePath, 'r');
+            fs.readSync(fd, buffer, 0, length, size - length);
+            fs.closeSync(fd);
+            return buffer.toString('utf8');
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return '';
+        }
+    }
+    readDir(dirPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.readdirSync(dirPath);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return [];
+        }
+    }
+    isDirectory(dirPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.statSync(dirPath).isDirectory();
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return false;
+        }
+    }
+    // 0 when the file is absent or unreadable — which reads as "no evidence", not "written long ago".
+    mtimeOf(filePath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.statSync(filePath).mtimeMs;
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return 0;
+        }
+    }
+};
+exports.HarnessAgentActivityReader = HarnessAgentActivityReader;
+exports.HarnessAgentActivityReader = HarnessAgentActivityReader = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], HarnessAgentActivityReader);
+//# sourceMappingURL=harness-agent-activity.js.map

package/src/harness-agent-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-agent-activity.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/harness-agent-activity.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { toError } from './to-error';\n\n/**\n * THE ONE PLACE THAT KNOWS ANYTHING ABOUT CLAUDE CODE'S ON-DISK STATE.\n *\n * ─── THE RULE THIS CLASS EXISTS UNDER ────────────────────────────────────────────────────────────\n *\n *      HARNESS STATE MAY ONLY VETO A REAP. IT MAY NEVER LICENSE ONE.\n *\n * Read that before reading anything else here, because every answer below is shaped by it. The\n * licence to remove a worktree comes SOLELY from evidence wp-cleanup already computes and already\n * gets right: a merged PR, a snapshot of a ref that still holds the work, a ref identical to\n * origin/main, plus a clean `git status --porcelain`. This class answers ONE question — \"is somebody\n * plausibly still in there?\" — and its only power is to STOP a reap that the branch evidence had\n * already authorised. No answer it can give turns a spared worktree into a reaped one.\n *\n * ─── WHY IT EXISTS ───────────────────────────────────────────────────────────────────────────────\n * `git worktree lock` reasons written by the Claude Code harness carry a pid, and wp-cleanup used to\n * ask the kernel whether that pid was alive. It always is. Subagents are NOT separate OS processes —\n * every agent in a session records the SAME pid, the session process — so \"is that pid running?\"\n * reduced to \"is the editor still open?\", which is true by construction for the whole life of a\n * session. Observed in monorepo-nx2: nine worktrees against a cap of five, eight of them reported as\n * \"that agent is working in here\" with one identical pid, exactly ONE agent actually running, and\n * several of the others' PRs already merged.\n *\n * So a veto has to come from somewhere that knows about AGENTS rather than processes. The harness\n * does, and it writes it down:\n *\n *     <config>/projects/<project-slug>/<sessionId>/subagents/agent-<id>.meta.json\n *     <config>/projects/<project-slug>/<sessionId>/subagents/agent-<id>.jsonl\n *\n * `<config>` is `$CLAUDE_CONFIG_DIR` when set, else `~/.claude`. `agent-<id>` is ONE token, and it is\n * the same token in three places: the stem of those two filenames, the basename of the `worktreePath`\n * that meta records, and the name in the lock reason `claude agent agent-<id> (pid N …)`. So worktree\n * → agent state is an exact lookup, not a heuristic — and nothing here re-derives or re-prefixes that\n * token, because a filename built from half of it is how a lookup quietly becomes a miss.\n *\n * ─── THE SIGNAL: THE SHAPE OF THE LAST RECORD IN THE AGENT'S OWN TRANSCRIPT ──────────────────────\n * An agent's loop pauses when the model emits text and asks for no tool. That is the definition of\n * the loop, not a correlation with one:\n *\n *   last record is `assistant` with NO `tool_use` block  →  RETURNED — not currently in a tool loop\n *   anything else (a `tool_use` block, a `user`/tool_result record)  →  MID-LOOP\n *\n * Verified on three agents known to have finished (all `assistant` / `['text']`) and on a live one\n * (`assistant` / `['tool_use']`). `thinking` blocks appear alongside `text` and change nothing: the\n * criterion is the ABSENCE of `tool_use`, never \"exactly one block\". A `user` record's content can be\n * a plain STRING rather than a list of blocks; that is mid-loop too, and must not throw.\n *\n * ─── \"RETURNED\" IS NOT \"DONE FOREVER\", WHICH IS WHY IT CANNOT LICENSE A REAP ──────────────────────\n * Measured: a throwaway agent returned with a text-only record at 17:04:20, and at 17:08:11 a `user`\n * record appeared and it ran again, returning a second time at 17:08:13. The harness RE-INVOKES an\n * agent when a background child it started completes, and when a parent sends it a message. It holds\n * its worktree across that gap. So RETURNED means \"not in a tool loop right now\" and nothing\n * stronger — which is survivable only because of the rule at the top of this file: the reap was\n * already authorised by a merged PR and a clean tree, and an agent that briefly resumes into that\n * situation has nothing to lose.\n *\n * ─── WHY MTIME IS ONLY A TIEBREAKER ──────────────────────────────────────────────────────────────\n * Freshness of the transcript looks like the obvious liveness signal and is NOT one. Measured: one\n * minute after that throwaway agent finished, its mtime was FRESHER than the genuinely live agent's\n * had been moments earlier. And a live agent writes nothing at all while it sits inside one long Bash\n * call — a `wp-build` is ten minutes of silence — so any threshold safe against that also covers\n * every just-finished agent, which is precisely the population wp-cleanup meets. Mtime alone does not\n * fix this bug; it re-times it. It earns its place on exactly one case: telling a mid-loop transcript\n * that is being written RIGHT NOW (a live agent, veto) from one frozen mid-`tool_use` by a killed\n * session (no veto — that is the original \"looks live forever\" defect).\n *\n * ─── NEGATIVE RESULT — DO NOT RE-TRY THIS ────────────────────────────────────────────────────────\n * The meta records a `toolUseId`, and a `tool_result` for it in the SPAWNER's transcript looks like an\n * exact completion marker. It is NOT one: a backgrounded Agent call gets its \"launched successfully\"\n * tool_result IMMEDIATELY, so a running agent already has one, indistinguishable from a finished\n * agent's. Measured on a live agent and rejected.\n *\n * ─── EVERY ANSWER FAILS SAFE ─────────────────────────────────────────────────────────────────────\n * A missing config dir, an unreadable file, a meta describing a different worktree, a truncated last\n * line — all of them are UNKNOWN. UNKNOWN withholds the veto, which is only ever safe because the\n * branch evidence had to authorise the reap first.\n *\n * THIS IS UNDOCUMENTED HARNESS INTERNALS, deliberately quarantined in one file so a layout change\n * breaks exactly here and degrades to \"cannot tell\" everywhere else.\n */\n\n/** Mid-loop and being written to right now. The ONE answer that vetoes a reap. */\nexport const AGENT_ACTIVITY_LIVE = 'live';\n/** Its transcript ends with the model returning — not in a tool loop. It may still resume. */\nexport const AGENT_ACTIVITY_RETURNED = 'returned';\n/** No usable evidence, or a mid-loop transcript nobody has touched for a long time. */\nexport const AGENT_ACTIVITY_UNKNOWN = 'unknown';\n\n/**\n * How long a MID-LOOP transcript may sit untouched before its silence stops vetoing a reap.\n *\n * Consulted for a mid-loop transcript only — a returned one is recognised by shape, whatever its\n * mtime — so this number decides exactly one thing: how long an agent that was KILLED inside a tool\n * call goes on vetoing. Generous on purpose, because a live agent writes NOTHING while it is inside\n * one long Bash call and a `wp-build` or `nx run … :ci` is routinely ten minutes of that. A threshold\n * in seconds would drop the veto on a building agent, which is the one direction that costs work;\n * being late costs a directory the next cleanup takes.\n */\nexport const AGENT_TRANSCRIPT_QUIET_MS = 45 * 60 * 1000;\n\n/**\n * How much of the tail of a transcript is read to find its last record.\n *\n * Transcripts are append-only and reach tens of megabytes; the answer lives in the final line. Large\n * enough that a single fat record (a big tool result) still fits whole — and when it does not, the\n * fragment fails to parse and the answer is UNKNOWN.\n */\nconst TRANSCRIPT_TAIL_BYTES = 8 * 1024 * 1024;\n\n// Data-only (per CLAUDE.md, classes for data). What the harness says about one agent, and why.\nexport class AgentActivity {\n    /** One of the AGENT_ACTIVITY_* constants. */\n    state: string;\n    /** Human-readable evidence, printed verbatim into wp-cleanup's spared/overridden reasons. */\n    detail: string;\n\n    constructor(state: string, detail: string) {\n        this.state = state;\n        this.detail = detail;\n    }\n}\n\n/**\n * Data-only. Where an agent's transcript is — or, when it is nowhere, WHICH of the three genuinely\n * different silences we hit.\n *\n * One flat \"no state file for that agent id\" covered all three, and two of them were untrue: a meta\n * that exists and cannot be PARSED, and a meta that exists and describes SOMEBODY ELSE'S worktree.\n * That string is printed verbatim into wp-cleanup's reason, so it is a message asserting more than\n * the evidence supports — the exact defect this whole file exists to remove, small and on the safe\n * side but the same shape.\n */\nclass AgentStateLookup {\n    /** The agent's own transcript, or '' when there is none to read. */\n    transcript: string;\n    /** When `transcript` is '': the honest reason, printed to a human as-is. */\n    detail: string;\n\n    constructor(transcript: string, detail: string) {\n        this.transcript = transcript;\n        this.detail = detail;\n    }\n}\n\n// Raw JSON shapes for the cast at the parse boundary — the convention merged-branches.ts already uses\n// for files it revives. Every field optional: this is somebody else's format.\ninterface RawAgentMeta {\n    worktreePath?: string;\n}\n\ninterface RawContentBlock {\n    type?: string;\n}\n\ninterface RawTranscriptMessage {\n    // A `user` record's content is sometimes a plain string rather than a list of blocks.\n    content?: RawContentBlock[] | string;\n}\n\ninterface RawTranscriptRecord {\n    type?: string;\n    message?: RawTranscriptMessage;\n}\n\n@injectable(bindingScopeValues.Singleton)\nexport class HarnessAgentActivityReader {\n    /**\n     * What the harness says about `agentId`, cross-checked against the worktree we are judging.\n     *\n     * `worktreePath` is not decoration: it is what makes this a LOOKUP rather than a guess. If the\n     * meta we find records a different worktree we have matched the wrong thing, and the answer is\n     * UNKNOWN — never an answer about somebody else's directory.\n     */\n    activityOf(agentId: string, worktreePath: string, now: number = Date.now()): AgentActivity {\n        const found = this.locate(agentId, worktreePath);\n        if (found.transcript === '') return new AgentActivity(AGENT_ACTIVITY_UNKNOWN, found.detail);\n        const last = this.lastRecord(found.transcript);\n        if (last === null) {\n            return new AgentActivity(AGENT_ACTIVITY_UNKNOWN, 'its transcript could not be read to the end');\n        }\n        if (this.isReturn(last)) {\n            return new AgentActivity(AGENT_ACTIVITY_RETURNED,\n                'its transcript ends with that agent returning its answer, so it is not in a tool call');\n        }\n        const written = this.mtimeOf(found.transcript);\n        if (written > 0 && now - written < AGENT_TRANSCRIPT_QUIET_MS) {\n            return new AgentActivity(AGENT_ACTIVITY_LIVE,\n                `its transcript ends mid-tool-call and was written ${this.minutesAgo(now, written)}`);\n        }\n        return new AgentActivity(AGENT_ACTIVITY_UNKNOWN,\n            'its transcript ends mid-tool-call but nothing has written to it for a long time, so that '\n            + 'agent was more likely killed than working');\n    }\n\n    /**\n     * Did the agent RETURN? True only for an `assistant` record whose content asks for no tool.\n     *\n     * A `user` record (a tool result coming back, or a message sent to the agent) is mid-loop by\n     * definition — and its content may be a plain string, which is why the array check comes first. So\n     * is an `assistant` record carrying a `tool_use` EVEN ALONGSIDE TEXT: the model narrating before\n     * it calls something is not a return.\n     */\n    private isReturn(record: RawTranscriptRecord): boolean {\n        if ((record.type ?? '') !== 'assistant') return false;\n        const content = record.message === undefined ? undefined : record.message.content;\n        if (!Array.isArray(content) || content.length === 0) return false;\n        for (const block of content) {\n            if ((block.type ?? '') === 'tool_use') return false;\n        }\n        return true;\n    }\n\n    /**\n     * The agent's own transcript, or the reason there is none — each of the three exits phrased for\n     * what actually happened. `exists` is asked BEFORE `readMeta` precisely so \"not there\" and\n     * \"there and unreadable\" stay distinguishable; folding them together is what produced the flat\n     * over-claim this replaced.\n     */\n    private locate(agentId: string, worktreePath: string): AgentStateLookup {\n        for (const subagents of this.subagentDirs()) {\n            const metaPath = path.join(subagents, `${agentId}.meta.json`);\n            if (!this.exists(metaPath)) continue;\n            const meta = this.readMeta(metaPath);\n            if (meta === null) {\n                return new AgentStateLookup('',\n                    `that agent's harness state file (${metaPath}) could not be read`);\n            }\n            const recorded = meta.worktreePath ?? '';\n            if (recorded !== '' && worktreePath !== '' && path.resolve(recorded) !== path.resolve(worktreePath)) {\n                return new AgentStateLookup('',\n                    `the harness records that agent against a different worktree (${recorded})`);\n            }\n            return new AgentStateLookup(path.join(subagents, `${agentId}.jsonl`), '');\n        }\n        return new AgentStateLookup('', 'the Claude Code harness has no state file for that agent id');\n    }\n\n    /** Every `<config>/projects/<slug>/<session>/subagents` directory that exists right now. */\n    private subagentDirs(): string[] {\n        const out: string[] = [];\n        const root = this.projectsRoot();\n        for (const project of this.readDir(root)) {\n            const projectDir = path.join(root, project);\n            for (const session of this.readDir(projectDir)) {\n                const subagents = path.join(projectDir, session, 'subagents');\n                if (this.isDirectory(subagents)) out.push(subagents);\n            }\n        }\n        return out;\n    }\n\n    /**\n     * Seam: where the harness keeps its per-project state. `$CLAUDE_CONFIG_DIR` wins when set, which\n     * is how the harness itself resolves it; specs override this to point at a fixture tree.\n     */\n    protected projectsRoot(): string {\n        const configured = process.env['CLAUDE_CONFIG_DIR'] ?? '';\n        const root = configured !== '' ? configured : path.join(os.homedir(), '.claude');\n        return path.join(root, 'projects');\n    }\n\n    private minutesAgo(now: number, written: number): string {\n        const minutes = Math.max(0, Math.floor((now - written) / 60000));\n        return minutes === 1 ? '1 minute ago' : `${String(minutes)} minutes ago`;\n    }\n\n    // ── Everything below is a guarded filesystem read: any failure is silence, never a throw. ──\n\n    private exists(filePath: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.existsSync(filePath);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return false;\n        }\n    }\n\n    // null means \"it is there and this release could not make sense of it\" — NOT \"it is absent\".\n    private readMeta(metaPath: string): RawAgentMeta | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return JSON.parse(fs.readFileSync(metaPath, 'utf8')) as RawAgentMeta;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    /**\n     * The last complete JSONL record of `transcript`, or null.\n     *\n     * Reads only the tail, because these files grow without bound and only the final line matters. A\n     * window that starts mid-record yields an unparseable fragment and therefore null — \"cannot tell\"\n     * — which is exactly what a truncated or half-written last line should also produce.\n     */\n    private lastRecord(transcript: string): RawTranscriptRecord | null {\n        const lines = this.readTail(transcript).split('\\n')\n            .filter((line: string): boolean => line.trim() !== '');\n        if (lines.length === 0) return null;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return JSON.parse(lines[lines.length - 1]) as RawTranscriptRecord;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    private readTail(filePath: string): string {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const size = fs.statSync(filePath).size;\n            const length = Math.min(size, TRANSCRIPT_TAIL_BYTES);\n            const buffer = Buffer.alloc(length);\n            const fd = fs.openSync(filePath, 'r');\n            fs.readSync(fd, buffer, 0, length, size - length);\n            fs.closeSync(fd);\n            return buffer.toString('utf8');\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n\n    private readDir(dirPath: string): string[] {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.readdirSync(dirPath);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return [];\n        }\n    }\n\n    private isDirectory(dirPath: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.statSync(dirPath).isDirectory();\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return false;\n        }\n    }\n\n    // 0 when the file is absent or unreadable — which reads as \"no evidence\", not \"written long ago\".\n    private mtimeOf(filePath: string): number {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.statSync(filePath).mtimeMs;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return 0;\n        }\n    }\n}\n"]}

package/src/index.d.ts

@@ -75,7 +75,8 @@ export { MergedBranch, DeletableBranch, DeletableWorktree, MergedBranchesCache,
 export { BranchArchiver, ArchiveResult, ARCHIVE_TAG_PREFIX, BRANCH_RETENTIONS, BRANCH_RETENTION_DELETE, BRANCH_RETENTION_ARCHIVE_TAG, BRANCH_RETENTION_KEEP, } from './branch-archiver';
 export { Worktree, WorktreeWorkInFlight, WorktreeService, } from './worktrees';
 export { AgentWorktreeLock, AgentWorktreeLockReader, } from './agent-worktree-lock';
-export { WorktreeLockVerdicts } from './worktree-lock-verdicts';
+export { HARNESS_NOT_CONSULTED, LOCK_LIVENESS_UNVERIFIABLE, LockDecision, LockEvidence, WorktreeLockVerdicts, } from './worktree-lock-verdicts';
+export { AGENT_ACTIVITY_LIVE, AGENT_ACTIVITY_RETURNED, AGENT_ACTIVITY_UNKNOWN, AGENT_TRANSCRIPT_QUIET_MS, AgentActivity, HarnessAgentActivityReader, } from './harness-agent-activity';
 export { ReapedBranch, ReapResult, BranchReaper, } from './branch-reaper';
 export { ReapedWorktree, WorktreeReapResult, WorktreeReaper, } from './worktree-reaper';
 export type { MutationVerb, MutationPhase } from './branch-mutation-log';

package/src/index.js

@@ -7,7 +7,7 @@ exports.NoSymbolDiTokensConfig = exports.AngularNoDirectApiInResolverConfig = ex
 exports.defaultLandPrConfig = exports.defaultPrGateConfig = exports.defaultGates = exports.ReviewContextEntry = exports.DEFAULT_DEV_BRANCH = exports.DEFAULT_DEV_BRANCH_NAMESPACE = exports.DevDeployConfig = exports.LandPrConfig = exports.DEFAULT_BUILD_COMMAND = exports.PrGateConfig = exports.GateDefinition = exports.BranchStateGuardConfig = exports.DEFAULT_BANNED_STATE_PATH_PREFIXES = exports.DEFAULT_TEMPLATE_DIRS = exports.NoStatePathsInTemplatesConfig = exports.CLIENT_CREATION_SEVERITIES = exports.NoClientCreationOutsideServerOrClientConfig = exports.VALIDATE_TS_MODES = exports.STRUCTURAL_MODES = exports.ON_OFF_MODES = exports.THROW_CAUSE_MODES = exports.DIRECT_API_RESOLVER_MODES = exports.PRISMA_CONVERTER_MODES = exports.PRISMA_DTOS_MODES = exports.PROJECT_MODES = exports.MODIFIED_CODE_MODES = exports.INLINE_TYPE_MODES = exports.RETURN_TYPE_MODES = exports.FILE_LIMIT_MODES = exports.METHOD_LIMIT_MODES = exports.BaseRuleConfig = exports.ValidateEslintSyncConfig = exports.ValidateVersionsLockedConfig = exports.ValidatePackageJsonConfig = exports.ValidateNoArchitectureCyclesConfig = exports.ValidateArchitectureUnchangedConfig = exports.ValidateTsInSrcConfig = exports.NoJsFilesConfig = exports.DiGraphConfig = exports.NxWiringConfig = exports.RuntimeArchitectureConfig = exports.NoFileImportCyclesConfig = exports.PrLifecycleGuardConfig = exports.BranchCreationGuardConfig = exports.RoleTagConfig = exports.FrameworkTagConfig = exports.InjectAnnotationNotNeededForConcreteClassConfig = exports.NoFunctionOutsideClassConfig = exports.NoProcessExitOutsideMainConfig = exports.NoCustomCssConfig = void 0;
 exports.CK_UNAUTHORIZED = exports.CK_BAD_FORMAT = exports.CK_MISSING = exports.CK_FAIL = exports.CK_OVERRIDDEN = exports.CK_WARN = exports.CK_PASS = exports.ChecklistVerdict = exports.ChecklistResult = exports.PrContext = exports.ReviewJson = exports.DEFAULT_RETENTION_DAYS = exports.ProvenanceWriteRequest = exports.OfferedContext = exports.ReviewerPaths = exports.ReviewerTranscript = exports.ReviewProvenance = exports.ReviewProvenanceService = exports.PROVENANCE_SKIPPED = exports.PROVENANCE_MISSING = exports.PROVENANCE_OK = exports.ProvenanceResult = exports.TranscriptScan = exports.ReviewerContext = exports.ReviewerEvidence = exports.SubagentProvenanceService = exports.verifyGateToken = exports.extractGateToken = exports.gateTokenMarker = exports.computeGateToken = exports.GateTokenService = exports.ALL_DIFF_ONE_READ_LINES = exports.READ_TRUNCATION_LINES = exports.ContextEntry = exports.BriefedFile = exports.ReviewerBriefing = exports.ReviewerInstructionsService = exports.ChecklistInstructionsService = exports.ChecklistValidator = exports.formatFileList = exports.normalizeChecklistDoc = exports.toChecklist = exports.ChecklistDefinition = exports.MERGE_MODES = exports.MERGE_MODE_NONE = exports.MERGE_MODE_AUTO = exports.buildDevDeployConfig = exports.buildLandPrConfig = exports.buildPrGateConfig = exports.defaultDevDeployConfig = void 0;
 exports.CACHE_STALE_AFTER_MS = exports.CacheFreshness = exports.MergedBranchesService = exports.MergedBranchesCache = exports.DeletableWorktree = exports.DeletableBranch = exports.MergedBranch = exports.squashRecoverySteps = exports.stampCleanMainSyncStatus = exports.computeMainSyncStatus = exports.finishedLock = exports.inProcessLock = exports.tryAcquireMainSyncLock = exports.isRefreshInProgress = exports.isLockStale = exports.writeMainSyncLock = exports.readMainSyncLock = exports.computeAllMainSyncStatuses = exports.writeMainSyncStatusFile = exports.writeMainSyncStatus = exports.readMainSyncStatusFile = exports.readMainSyncStatus = exports.mainSyncLockPath = exports.mainSyncStatusPath = exports.DEFAULT_HANG_TIMEOUT_MINUTES = exports.MainSyncStatusService = exports.MainSyncLock = exports.MAIN_SYNC_STATUS_VERSION = exports.PullRequestIndex = exports.MainSyncFileStore = exports.MainSyncStatusFile = exports.MainSyncStatus = exports.DEFAULT_APPROVAL_HOURS = exports.AUTHORIZATIONS_DIR = exports.HumanAuthorizationService = exports.AuthorizedOverrides = exports.AuthorizationCheck = exports.AuthorizationContext = exports.AuthorizationFile = exports.HumanApproval = exports.reviewJsonSchemaHint = exports.reviewJsonPath = exports.prDirFor = exports.ReviewJsonService = exports.ChecklistReviewContext = exports.RequiredChecklist = exports.VERDICT_STATUSES = exports.VERDICT_RED = exports.VERDICT_YELLOW = exports.VERDICT_GREEN = void 0;
-exports.DEFAULT_MERGE_COMPLETE_COMMAND = exports.DEFAULT_UPSERT_PR_COMMAND = exports.buildCommandsConfig = exports.CommandsConfig = exports.logBranchMutation = exports.branchMutationLogPath = exports.BranchMutationLog = exports.BranchMutationEvent = exports.WorktreeReaper = exports.WorktreeReapResult = exports.ReapedWorktree = exports.BranchReaper = exports.ReapResult = exports.ReapedBranch = exports.WorktreeLockVerdicts = exports.AgentWorktreeLockReader = exports.AgentWorktreeLock = exports.WorktreeService = exports.WorktreeWorkInFlight = exports.Worktree = exports.BRANCH_RETENTION_KEEP = exports.BRANCH_RETENTION_ARCHIVE_TAG = exports.BRANCH_RETENTION_DELETE = exports.BRANCH_RETENTIONS = exports.ARCHIVE_TAG_PREFIX = exports.ArchiveResult = exports.BranchArchiver = exports.ADJUDICATED_CLASSIFICATIONS = exports.CLASSIFICATION_DETACHED = exports.CLASSIFICATION_CURRENT = exports.CLASSIFICATION_LOCKED = exports.CLASSIFICATION_PRUNABLE = exports.CLASSIFICATION_IN_USE = exports.CLASSIFICATION_NEVER_PROPOSED = exports.CLASSIFICATION_CONTENT_IN_MAIN = exports.CLASSIFICATION_SUPERSEDED = exports.CLASSIFICATION_NO_COMMITS = exports.CLASSIFICATION_BACKUP_OF_LIVE = exports.CLASSIFICATION_BACKUP_OF_MERGED = exports.CLASSIFICATION_MERGED_PR = void 0;
+exports.DEFAULT_MERGE_COMPLETE_COMMAND = exports.DEFAULT_UPSERT_PR_COMMAND = exports.buildCommandsConfig = exports.CommandsConfig = exports.logBranchMutation = exports.branchMutationLogPath = exports.BranchMutationLog = exports.BranchMutationEvent = exports.WorktreeReaper = exports.WorktreeReapResult = exports.ReapedWorktree = exports.BranchReaper = exports.ReapResult = exports.ReapedBranch = exports.HarnessAgentActivityReader = exports.AgentActivity = exports.AGENT_TRANSCRIPT_QUIET_MS = exports.AGENT_ACTIVITY_UNKNOWN = exports.AGENT_ACTIVITY_RETURNED = exports.AGENT_ACTIVITY_LIVE = exports.WorktreeLockVerdicts = exports.LockEvidence = exports.LockDecision = exports.LOCK_LIVENESS_UNVERIFIABLE = exports.HARNESS_NOT_CONSULTED = exports.AgentWorktreeLockReader = exports.AgentWorktreeLock = exports.WorktreeService = exports.WorktreeWorkInFlight = exports.Worktree = exports.BRANCH_RETENTION_KEEP = exports.BRANCH_RETENTION_ARCHIVE_TAG = exports.BRANCH_RETENTION_DELETE = exports.BRANCH_RETENTIONS = exports.ARCHIVE_TAG_PREFIX = exports.ArchiveResult = exports.BranchArchiver = exports.ADJUDICATED_CLASSIFICATIONS = exports.CLASSIFICATION_DETACHED = exports.CLASSIFICATION_CURRENT = exports.CLASSIFICATION_LOCKED = exports.CLASSIFICATION_PRUNABLE = exports.CLASSIFICATION_IN_USE = exports.CLASSIFICATION_NEVER_PROPOSED = exports.CLASSIFICATION_CONTENT_IN_MAIN = exports.CLASSIFICATION_SUPERSEDED = exports.CLASSIFICATION_NO_COMMITS = exports.CLASSIFICATION_BACKUP_OF_LIVE = exports.CLASSIFICATION_BACKUP_OF_MERGED = exports.CLASSIFICATION_MERGED_PR = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "ResolvedConfig", { enumerable: true, get: function () { return types_1.ResolvedConfig; } });
 Object.defineProperty(exports, "ResolvedRuleConfig", { enumerable: true, get: function () { return types_1.ResolvedRuleConfig; } });
@@ -498,7 +498,18 @@ var agent_worktree_lock_1 = require("./agent-worktree-lock");
 Object.defineProperty(exports, "AgentWorktreeLock", { enumerable: true, get: function () { return agent_worktree_lock_1.AgentWorktreeLock; } });
 Object.defineProperty(exports, "AgentWorktreeLockReader", { enumerable: true, get: function () { return agent_worktree_lock_1.AgentWorktreeLockReader; } });
 var worktree_lock_verdicts_1 = require("./worktree-lock-verdicts");
+Object.defineProperty(exports, "HARNESS_NOT_CONSULTED", { enumerable: true, get: function () { return worktree_lock_verdicts_1.HARNESS_NOT_CONSULTED; } });
+Object.defineProperty(exports, "LOCK_LIVENESS_UNVERIFIABLE", { enumerable: true, get: function () { return worktree_lock_verdicts_1.LOCK_LIVENESS_UNVERIFIABLE; } });
+Object.defineProperty(exports, "LockDecision", { enumerable: true, get: function () { return worktree_lock_verdicts_1.LockDecision; } });
+Object.defineProperty(exports, "LockEvidence", { enumerable: true, get: function () { return worktree_lock_verdicts_1.LockEvidence; } });
 Object.defineProperty(exports, "WorktreeLockVerdicts", { enumerable: true, get: function () { return worktree_lock_verdicts_1.WorktreeLockVerdicts; } });
+var harness_agent_activity_1 = require("./harness-agent-activity");
+Object.defineProperty(exports, "AGENT_ACTIVITY_LIVE", { enumerable: true, get: function () { return harness_agent_activity_1.AGENT_ACTIVITY_LIVE; } });
+Object.defineProperty(exports, "AGENT_ACTIVITY_RETURNED", { enumerable: true, get: function () { return harness_agent_activity_1.AGENT_ACTIVITY_RETURNED; } });
+Object.defineProperty(exports, "AGENT_ACTIVITY_UNKNOWN", { enumerable: true, get: function () { return harness_agent_activity_1.AGENT_ACTIVITY_UNKNOWN; } });
+Object.defineProperty(exports, "AGENT_TRANSCRIPT_QUIET_MS", { enumerable: true, get: function () { return harness_agent_activity_1.AGENT_TRANSCRIPT_QUIET_MS; } });
+Object.defineProperty(exports, "AgentActivity", { enumerable: true, get: function () { return harness_agent_activity_1.AgentActivity; } });
+Object.defineProperty(exports, "HarnessAgentActivityReader", { enumerable: true, get: function () { return harness_agent_activity_1.HarnessAgentActivityReader; } });
 var branch_reaper_1 = require("./branch-reaper");
 Object.defineProperty(exports, "ReapedBranch", { enumerable: true, get: function () { return branch_reaper_1.ReapedBranch; } });
 Object.defineProperty(exports, "ReapResult", { enumerable: true, get: function () { return branch_reaper_1.ReapResult; } });