@cluesmith/codev 3.2.4 → 3.3.0

package/dist/agent-farm/commands/interrupt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Interrupt command — send a bare ESC keystroke into a builder's PTY (Spec 1273).
+ *
+ * This is the only recovery that reaches a builder *mid-turn*. When a builder
+ * chains foreground waits inside one turn, every `afx send` — including the
+ * architect's order to stop — queues unread until the turn ends. ESC interrupts
+ * the running tool, ends the turn, and the queued messages then process.
+ *
+ * Verified in production (shannon workspace, 2026-07-27): a builder wedged for
+ * 45+ minutes on a wait for a file whose producer had already died resumed
+ * within two minutes of receiving ESC. Until now that recipe
+ * (`afx send <builder> --raw "$(printf '\x1b')"`) lived only in architect lore
+ * and had to be discovered under pressure.
+ *
+ * Addressing, workspace detection and sender identity are reused verbatim from
+ * `afx send` — there is exactly one address resolver.
+ */
+import type { InterruptOptions } from '../types.js';
+export declare function interrupt(options: InterruptOptions): Promise<void>;
+//# sourceMappingURL=interrupt.d.ts.map

package/dist/agent-farm/commands/interrupt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/commands/interrupt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKpD,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDxE"}

package/dist/agent-farm/commands/interrupt.js

@@ -0,0 +1,65 @@
+/**
+ * Interrupt command — send a bare ESC keystroke into a builder's PTY (Spec 1273).
+ *
+ * This is the only recovery that reaches a builder *mid-turn*. When a builder
+ * chains foreground waits inside one turn, every `afx send` — including the
+ * architect's order to stop — queues unread until the turn ends. ESC interrupts
+ * the running tool, ends the turn, and the queued messages then process.
+ *
+ * Verified in production (shannon workspace, 2026-07-27): a builder wedged for
+ * 45+ minutes on a wait for a file whose producer had already died resumed
+ * within two minutes of receiving ESC. Until now that recipe
+ * (`afx send <builder> --raw "$(printf '\x1b')"`) lived only in architect lore
+ * and had to be discovered under pressure.
+ *
+ * Addressing, workspace detection and sender identity are reused verbatim from
+ * `afx send` — there is exactly one address resolver.
+ */
+import { logger, fatal } from '../utils/logger.js';
+import { TowerClient } from '../lib/tower-client.js';
+import { detectWorkspaceRoot, detectCurrentBuilderId } from './send.js';
+export async function interrupt(options) {
+    const target = options.builder;
+    if (!target) {
+        fatal('Must specify a builder. Usage: afx interrupt <builder>');
+    }
+    logger.header('Sending Interrupt (ESC)');
+    const workspace = detectWorkspaceRoot() ?? undefined;
+    // Same identity rule as `afx send`: in a confirmed builder worktree an
+    // unverifiable canonical id aborts rather than sending as an unverified
+    // sender, which Tower would silently route to 'main' (issue #1094).
+    let from;
+    try {
+        from = detectCurrentBuilderId() ?? 'architect';
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    const client = new TowerClient();
+    if (!(await client.isRunning())) {
+        fatal('Tower is not running. Start it with: afx tower start');
+    }
+    try {
+        // `message` carries the ESC byte so the route's non-empty validation is
+        // satisfied and both this command and the manual `--raw` recipe exercise the
+        // same byte. `escape` is what makes delivery immediate and unformatted.
+        const result = await client.sendMessage(target, '\x1b', {
+            from,
+            workspace,
+            fromWorkspace: workspace,
+            escape: true,
+            noEnter: options.noEnter,
+        });
+        if (!result.ok) {
+            throw new Error(result.error || 'Unknown error');
+        }
+        logger.success(`Interrupt (ESC) sent to ${result.resolvedTo ?? target}`);
+        if (!options.noEnter) {
+            logger.info('Enter followed the ESC — any messages queued during the turn should now process.');
+        }
+    }
+    catch (error) {
+        fatal(error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=interrupt.js.map

package/dist/agent-farm/commands/interrupt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt.js","sourceRoot":"","sources":["../../../src/agent-farm/commands/interrupt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExE,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAE/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,yBAAyB,CAAC,CAAC;IAEzC,MAAM,SAAS,GAAG,mBAAmB,EAAE,IAAI,SAAS,CAAC;IAErD,uEAAuE;IACvE,wEAAwE;IACxE,oEAAoE;IACpE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,sBAAsB,EAAE,IAAI,WAAW,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;QAChC,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,CAAC;QACH,wEAAwE;QACxE,6EAA6E;QAC7E,wEAAwE;QACxE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE;YACtD,IAAI;YACJ,SAAS;YACT,aAAa,EAAE,SAAS;YACxB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,eAAe,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,CAAC,OAAO,CAAC,2BAA2B,MAAM,CAAC,UAAU,IAAI,MAAM,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/agent-farm/commands/reset/constants.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tunable parameters for `afx reset` (Spec 1273).
+ *
+ * Every value here is overridable from the CLI. The defaults are grounded in
+ * the one verified manual reset (shannon workspace, 2026-07-27), not guessed.
+ */
+/**
+ * Fixed name of the builder's working-state file, at the worktree root.
+ *
+ * The `.builder-` prefix is load-bearing: `afx cleanup` classifies untracked
+ * `.builder-*` files as scaffold rather than dirt, so a worktree carrying one is
+ * still considered clean. It is untracked, which is why `porch done`'s
+ * staged-file sweep cannot pick it up.
+ *
+ * The name is deliberately FIXED rather than nonce-suffixed. Freshness is proven
+ * by the nonce *inside* the file (R2), so encoding it in the filename would add
+ * nothing and would leave a new litter file after every reset.
+ */
+export declare const STATE_FILE_NAME = ".builder-state.md";
+/** Long-form re-orientation written before the clear (R1). Same prefix rationale. */
+export declare const REORIENT_FILE_NAME = ".builder-reorient.md";
+/**
+ * Minimum size for a state file to count as substantive.
+ *
+ * The one verified example ran 203 lines (~8-10KB). A genuine cold-reader save
+ * is comfortably over 1KB; a three-line stub is 100-200 bytes. 1000 rejects
+ * stubs without false-rejecting a terse but real save.
+ */
+export declare const DEFAULT_MIN_BYTES = 1000;
+/** Gap between the two observations that must agree for the file to count as stable. */
+export declare const DEFAULT_STABILITY_WINDOW_MS = 2000;
+/** How often to stat the state file while waiting for it. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 2000;
+/**
+ * How long to wait for the builder to produce the state file.
+ *
+ * A busy builder may take minutes to reach the request — the manual run was of
+ * this order. Expiry aborts WITHOUT clearing (R2).
+ */
+export declare const DEFAULT_RECEIPT_TIMEOUT_MS = 300000;
+/**
+ * How long the terminal must produce no output before it counts as quiescent.
+ *
+ * An agent mid-turn emits continuously (spinner frames, streamed tokens), so a
+ * true silence of this length reliably indicates the turn ended.
+ */
+export declare const DEFAULT_QUIET_WINDOW_MS = 1500;
+/** Bounded wait for quiescence before the single ESC escalation (R4). */
+export declare const DEFAULT_QUIESCE_TIMEOUT_MS = 60000;
+/** Bounded wait after the ESC escalation. Shorter — ESC should act immediately. */
+export declare const DEFAULT_QUIESCE_POST_ESCALATION_TIMEOUT_MS = 30000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/agent-farm/commands/reset/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/commands/reset/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,sBAAsB,CAAC;AAEnD,qFAAqF;AACrF,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,wFAAwF;AACxF,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,mFAAmF;AACnF,eAAO,MAAM,0CAA0C,QAAS,CAAC"}

package/dist/agent-farm/commands/reset/constants.js

@@ -0,0 +1,52 @@
+/**
+ * Tunable parameters for `afx reset` (Spec 1273).
+ *
+ * Every value here is overridable from the CLI. The defaults are grounded in
+ * the one verified manual reset (shannon workspace, 2026-07-27), not guessed.
+ */
+/**
+ * Fixed name of the builder's working-state file, at the worktree root.
+ *
+ * The `.builder-` prefix is load-bearing: `afx cleanup` classifies untracked
+ * `.builder-*` files as scaffold rather than dirt, so a worktree carrying one is
+ * still considered clean. It is untracked, which is why `porch done`'s
+ * staged-file sweep cannot pick it up.
+ *
+ * The name is deliberately FIXED rather than nonce-suffixed. Freshness is proven
+ * by the nonce *inside* the file (R2), so encoding it in the filename would add
+ * nothing and would leave a new litter file after every reset.
+ */
+export const STATE_FILE_NAME = '.builder-state.md';
+/** Long-form re-orientation written before the clear (R1). Same prefix rationale. */
+export const REORIENT_FILE_NAME = '.builder-reorient.md';
+/**
+ * Minimum size for a state file to count as substantive.
+ *
+ * The one verified example ran 203 lines (~8-10KB). A genuine cold-reader save
+ * is comfortably over 1KB; a three-line stub is 100-200 bytes. 1000 rejects
+ * stubs without false-rejecting a terse but real save.
+ */
+export const DEFAULT_MIN_BYTES = 1000;
+/** Gap between the two observations that must agree for the file to count as stable. */
+export const DEFAULT_STABILITY_WINDOW_MS = 2000;
+/** How often to stat the state file while waiting for it. */
+export const DEFAULT_POLL_INTERVAL_MS = 2000;
+/**
+ * How long to wait for the builder to produce the state file.
+ *
+ * A busy builder may take minutes to reach the request — the manual run was of
+ * this order. Expiry aborts WITHOUT clearing (R2).
+ */
+export const DEFAULT_RECEIPT_TIMEOUT_MS = 300_000;
+/**
+ * How long the terminal must produce no output before it counts as quiescent.
+ *
+ * An agent mid-turn emits continuously (spinner frames, streamed tokens), so a
+ * true silence of this length reliably indicates the turn ended.
+ */
+export const DEFAULT_QUIET_WINDOW_MS = 1500;
+/** Bounded wait for quiescence before the single ESC escalation (R4). */
+export const DEFAULT_QUIESCE_TIMEOUT_MS = 60_000;
+/** Bounded wait after the ESC escalation. Shorter — ESC should act immediately. */
+export const DEFAULT_QUIESCE_POST_ESCALATION_TIMEOUT_MS = 30_000;
+//# sourceMappingURL=constants.js.map

package/dist/agent-farm/commands/reset/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/agent-farm/commands/reset/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAEnD,qFAAqF;AACrF,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,wFAAwF;AACxF,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C,yEAAyE;AACzE,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD,mFAAmF;AACnF,MAAM,CAAC,MAAM,0CAA0C,GAAG,MAAM,CAAC"}

package/dist/agent-farm/commands/reset/context.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Builder context resolution for `afx reset` (Spec 1273, phase 4).
+ *
+ * Invariant R3 requires a re-orientation carrying protocol, mode, worktree,
+ * branch, project identity and porch re-entry. The first draft of the plan
+ * assumed the builder registry held those facts. **It does not**, and the gap is
+ * silent rather than obvious:
+ *
+ *   - `builders.protocol_name` is NULL for spec-type builders. `spawn.ts` never
+ *     passes `protocolName` on that path (only the `protocol`-type spawn does),
+ *     so every SPIR/ASPIR lane — precisely the long-running builders this feature
+ *     exists for — has NULL there. Reading `db/schema.ts` shows the column and
+ *     looks fine; the persistence path is where the truth is.
+ *   - Mode is not persisted at all. `resolveMode` computes it at spawn from flags
+ *     plus protocol defaults and discards it, so a spawn-time `--soft` cannot be
+ *     recovered afterwards by recomputation.
+ *   - Harness comes from workspace config, which can change while a builder runs,
+ *     so config is not authoritative for a *running* builder.
+ *
+ * So this module reads the worktree, which holds all of it authoritatively:
+ * porch's `status.yaml` (protocol, phase), `.builder-prompt.txt` (the literal
+ * `## Mode:` line the builder was given), and `.builder-start.sh` (the launch
+ * line of the process actually running).
+ *
+ * Every chain ends in a **loud abort**, never a default. A guessed protocol or
+ * mode would produce a plausible-looking re-orientation that quietly reframes the
+ * builder — the exact drift R3 exists to prevent.
+ */
+import { type CustomHarnessConfig, type HarnessProvider } from '../../utils/harness.js';
+/** Filesystem access needed for resolution. Injected so tests need no worktree. */
+export interface ContextFsPort {
+    exists(path: string): boolean;
+    read(path: string): string | null;
+    /** Immediate subdirectory names, or null when the directory does not exist. */
+    listDirs(path: string): string[] | null;
+}
+export interface ResolvedBuilderContext {
+    builderId: string;
+    worktree: string;
+    branch: string;
+    protocol: string;
+    /** Where the protocol came from — surfaced in the report so it is auditable. */
+    protocolSource: 'status.yaml' | 'builder-id';
+    mode: 'strict' | 'soft';
+    modeSource: 'flag' | 'builder-prompt' | 'task-default';
+    harnessName: string;
+    harness: HarnessProvider;
+    /** Null for a non-porch lane; that is a branch, not a failure. */
+    porch: PorchContext | null;
+    /**
+     * Artifact identity, for phase 5's reconstruction of the spawn TemplateContext.
+     *
+     * Null on a non-porch lane, where there is no spec/plan naming convention to
+     * derive from. `specPath`/`planPath` are worktree-relative and are only set
+     * when the file actually exists — a pointer to a file that is not there would
+     * send a freshly-reset builder chasing a ghost.
+     */
+    specName: string | null;
+    specPath: string | null;
+    planPath: string | null;
+    /** Issue number, from the registry row or the porch project id. */
+    issueNumber?: string;
+    /**
+     * Ad-hoc task text, from the registry row (`builders.task_text`).
+     *
+     * Present only for `afx spawn --task` builders. Phase 5 needs it to tell that
+     * lane apart from the others: a task builder still gets a porch project keyed
+     * on its builder id, so `issueNumber` is populated for it too, and without
+     * this field the task lane is indistinguishable from an issue-driven one.
+     */
+    taskText?: string;
+    /**
+     * True only for a BARE `afx spawn --task` builder (no `--protocol`).
+     *
+     * Established from positive evidence — task text present AND the prompt file
+     * carries no `## Mode:` heading — rather than inferred from the absence of a
+     * porch project. `initPorchInWorktree` is deliberately non-fatal, so a
+     * `--task --protocol X` builder whose porch init failed also has task text and
+     * no porch, and inferring from that would strip its real protocol template and
+     * hand it the raw task text instead.
+     *
+     * The prompt is built BEFORE porch init (`spawn.ts:545-548`), so a
+     * `--task --protocol` builder's prompt carries the rendered template — and its
+     * `## Mode:` line — regardless of whether porch init later succeeded.
+     */
+    isBareTask: boolean;
+}
+export interface PorchContext {
+    projectId: string;
+    projectName: string;
+    /** The protocol porch is actually running for this project. */
+    protocol: string;
+    phase: string;
+    currentPlanPhase: string | null;
+    statusPath: string;
+}
+/** Thrown when a fact cannot be established. Never swallowed into a default. */
+export declare class ContextResolutionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Locate and parse THIS BUILDER's porch status file.
+ *
+ * Returns null when this builder has no porch project — a task or shell builder
+ * is a legitimate reset target, it simply gets no porch re-entry block.
+ *
+ * ## Why this takes an identity instead of picking the first parsable file
+ *
+ * The first implementation returned the first directory under `codev/projects`
+ * with a parsable `status.yaml`. That is correct only for a repo holding exactly
+ * one project directory. **This repo commits porch history to `main`**, so every
+ * worktree inherits every project ever run — 203 of them at the time of writing.
+ * The alphabetically-first is `0087-porch-timeout-termination-retries`, whose
+ * protocol is `spider`, so `afx reset` resolved protocol "spider" for *every*
+ * builder and died on `Protocol "spider" has no builder-prompt.md`. It failed
+ * loudly, which is why nothing was corrupted — but it failed for every lane.
+ *
+ * The fix is to select by identity, never by position: a directory qualifies
+ * only when it belongs to the builder being reset. No match returns null, which
+ * is the honest answer for a genuinely non-porch builder and is also safe for a
+ * porch one — a missing porch block is visible in the re-orientation, whereas
+ * *another project's* protocol is a confident lie.
+ *
+ * (This is the #1235 wrong-winner family: pick-the-first over a set that is
+ * assumed to be a singleton and is not.)
+ *
+ * Parsed with targeted line matching rather than a YAML dependency: this module
+ * needs four scalar fields, and the file is machine-written by porch.
+ */
+export interface PorchProjectIdentity {
+    /** Registry builder id, e.g. `aspir-1273`, `builder-task-re_v`. */
+    builderId: string;
+    /** Issue number when the lane has one. */
+    issueNumber?: string;
+}
+/**
+ * Project ids this builder could legitimately own, most specific first.
+ *
+ * Three forms, because porch names projects differently per lane:
+ *   - the issue number, for issue-driven lanes;
+ *   - the builder id itself — `spawn.ts` passes `builderId` as the porch project
+ *     id on the `--task` path;
+ *   - the builder id with its protocol prefix stripped (`aspir-1273` → `1273`),
+ *     which is how spec-driven lanes are named.
+ */
+export declare function candidateProjectIds(identity: PorchProjectIdentity): string[];
+export declare function readPorchContext(fs: ContextFsPort, worktree: string, identity: PorchProjectIdentity): PorchContext | null;
+/**
+ * The protocol recorded in status.yaml, if there is one.
+ *
+ * Reads through `readPorchContext` rather than re-scanning the project dirs, so
+ * the two cannot disagree about which status.yaml is authoritative. Worktrees
+ * routinely hold MANY project directories here (porch history is committed to
+ * `main`), which is exactly why both go through one identity-aware selector.
+ */
+export declare function protocolFromStatus(fs: ContextFsPort, worktree: string, identity: PorchProjectIdentity): string | null;
+/**
+ * Read the mode the builder was actually told it was running in.
+ *
+ * The spawn prompt renders a literal `## Mode: STRICT` heading, and `--resume`
+ * does not rewrite the prompt file, so this stays correct across resumes. It is
+ * a stronger source than recomputing `resolveMode`, which cannot recover a
+ * spawn-time `--soft` from protocol defaults.
+ */
+export declare function modeFromBuilderPrompt(fs: ContextFsPort, worktree: string): 'strict' | 'soft' | null;
+/**
+ * Recover an issue number from a porch project id.
+ *
+ * Porch ids are not uniformly numeric. PIR and SPIR use the bare issue number;
+ * **BUGFIX deliberately uses `<prefix>-<N>`** (`spawn.ts:817`, "historical, kept
+ * untouched"). A strict `/^\d+$/` guard therefore threw away BUGFIX's issue
+ * identity whenever the registry row lacked one — and on BUGFIX the issue body
+ * IS the spec, so the re-orientation lost the requirements it was meant to carry.
+ *
+ * Accepts a bare number or a canonical `<word>-<number>`; rejects anything else,
+ * so an ad-hoc task id (`builder-task-abc`) still cannot masquerade as an issue.
+ */
+export declare function issueNumberFromPorchId(projectId?: string): string | undefined;
+/**
+ * Identify the harness from the worktree's launch script.
+ *
+ * Per-builder ground truth: the script is what the running process was started
+ * with, so it stays right even if workspace config changed since the spawn.
+ */
+export declare function harnessFromLaunchScript(fs: ContextFsPort, worktree: string, customHarnesses?: Record<string, CustomHarnessConfig>): string | null;
+/**
+ * Map a harness name to its provider, honouring project-defined custom harnesses.
+ *
+ * Custom harnesses resolve to a real provider rather than failing as
+ * "unrecognisable", so the refusal a project sees is the accurate one — *this
+ * harness cannot reset in-session* — instead of a misleading "unknown harness".
+ * `buildCustomHarnessProvider` does not set `supportsContextReset`, so custom
+ * harnesses are unsupported by default; letting one declare support would be a
+ * one-field addition to `CustomHarnessConfig`, deliberately out of scope here.
+ */
+export declare function harnessProviderFor(harnessName: string, customHarnesses?: Record<string, CustomHarnessConfig>): HarnessProvider | null;
+/**
+ * Derive artifact identity from the porch project.
+ *
+ * Porch names its project dir `<id>-<title>`, and spec/plan files share that
+ * stem by convention (`codev/specs/<id>-<title>.md`). Paths are returned only
+ * when the file exists.
+ */
+export declare function artifactPaths(fs: ContextFsPort, worktree: string, porch: PorchContext | null): {
+    specName: string | null;
+    specPath: string | null;
+    planPath: string | null;
+};
+export interface ResolveContextOptions {
+    fs: ContextFsPort;
+    builderId: string;
+    worktree: string;
+    branch: string;
+    issueNumber?: string;
+    /** `builders.task_text`, for `--task` builders. Forwarded verbatim. */
+    taskText?: string;
+    /** `--mode` override; wins over the worktree, for when the prompt file is gone. */
+    modeOverride?: 'strict' | 'soft';
+    /** Project-defined harnesses from `.codev/config.json`, if any. */
+    customHarnesses?: Record<string, CustomHarnessConfig>;
+}
+/**
+ * Resolve everything the re-orientation needs, or throw.
+ *
+ * Deliberately does NOT consult `builders.protocol_name`: it is NULL for
+ * spec-type builders, so a reader who "fixed" this to use the registry would
+ * break exactly the lanes the feature targets while the code looked more correct.
+ */
+export declare function resolveBuilderContext(options: ResolveContextOptions): ResolvedBuilderContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/agent-farm/commands/reset/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/commands/reset/context.ts"],"names":[],"mappings":"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"}