@cluesmith/codev 3.2.4 → 3.3.1

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

@@ -0,0 +1,428 @@
+/**
+ * Builder context resolution for `afx refresh` (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 { join } from 'node:path';
+import { parseAgentName } from '../../utils/agent-names.js';
+import { BUILTIN_HARNESSES, getBuiltinHarness, buildCustomHarnessProvider, } from '../../utils/harness.js';
+/** Thrown when a fact cannot be established. Never swallowed into a default. */
+export class ContextResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ContextResolutionError';
+    }
+}
+/**
+ * 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 function candidateProjectIds(identity) {
+    const out = [];
+    if (identity.issueNumber)
+        out.push(identity.issueNumber);
+    // The raw registry id, INCLUDING any `builder-` prefix. `spawn --task
+    // --protocol X` passes `builderId` straight to `porch init`
+    // (`spawn.ts:548`), and `initPorchInWorktree` keeps dashes when sanitising
+    // (`spawn-worktree.ts:472`), so that lane's porch project id really is
+    // `builder-task-<id>`. Omitting this form orphaned it: porch resolved to
+    // null, and the builder was re-oriented as protocol TASK with no porch
+    // re-entry — a silently degraded frame rather than a loud failure.
+    out.push(identity.builderId);
+    // And without the prefix, which is how spec/bugfix lanes are named.
+    const bare = identity.builderId.replace(/^builder-/, '');
+    if (bare !== identity.builderId)
+        out.push(bare);
+    const dash = bare.indexOf('-');
+    if (dash > 0)
+        out.push(bare.slice(dash + 1));
+    return out.filter(v => v !== '');
+}
+/**
+ * Compare ids ignoring case and leading zeros.
+ *
+ * Case: the registry lowercases builder ids while worktree and directory names
+ * preserve the original (`builder-task-re_v` vs `.builders/task-RE_V`). macOS
+ * hides that; a case-sensitive filesystem would not.
+ * Leading zeros: project dirs use `0087-…` while porch ids and CLI arguments use
+ * `87` (`afx cleanup -p 466` vs `0466` is the same long-standing split).
+ */
+function normalizeId(value) {
+    return value.trim().toLowerCase().replace(/^0+(?=\d)/, '');
+}
+function claimStrength(dir, statusId, identity) {
+    const rawId = normalizeId(identity.builderId);
+    if (statusId && normalizeId(statusId) === rawId && !/^\d+$/.test(rawId))
+        return 'strong';
+    const wanted = candidateProjectIds(identity).map(normalizeId);
+    // A status.yaml that STATES its id is authoritative about what it is. If that
+    // id does not claim this builder, the directory name cannot overrule it —
+    // `codev/projects/1273-old/` holding `id: '999'` belongs to 999, whatever the
+    // directory is called. Falling through to the name here let a renamed or
+    // recycled directory claim a builder, and manufactured false ambiguities
+    // alongside the real project.
+    if (statusId)
+        return wanted.includes(normalizeId(statusId)) ? 'weak' : 'none';
+    // Directory-name fallback applies ONLY when the file states no id at all.
+    const dirNorm = normalizeId(dir);
+    return wanted.some(c => dirNorm === c || dirNorm.startsWith(`${c}-`)) ? 'weak' : 'none';
+}
+export function readPorchContext(fs, worktree, identity) {
+    const projectsDir = join(worktree, 'codev', 'projects');
+    const dirs = fs.listDirs(projectsDir);
+    if (!dirs || dirs.length === 0)
+        return null;
+    // The protocol the builder id claims, used to corroborate weak (number-only)
+    // matches. Absent for ids that are not in canonical form, in which case a weak
+    // match cannot be corroborated and is not trusted.
+    const expectedProtocol = parseAgentName(identity.builderId)?.protocol ?? null;
+    const strong = [];
+    const weak = [];
+    for (const dir of dirs) {
+        const statusPath = join(projectsDir, dir, 'status.yaml');
+        const content = fs.read(statusPath);
+        if (content === null)
+            continue;
+        const protocol = matchScalar(content, 'protocol');
+        const phase = matchScalar(content, 'phase');
+        const id = matchScalar(content, 'id');
+        if (!protocol || !phase)
+            continue;
+        const claim = claimStrength(dir, id, identity);
+        if (claim === 'none')
+            continue;
+        const currentPlanPhase = matchScalar(content, 'current_plan_phase');
+        const ctx = {
+            projectId: id ?? dir.split('-')[0],
+            projectName: dir,
+            protocol,
+            phase,
+            currentPlanPhase: currentPlanPhase && currentPlanPhase !== 'null' ? currentPlanPhase : null,
+            statusPath,
+        };
+        if (claim === 'strong') {
+            strong.push(ctx);
+            continue;
+        }
+        // A weak match must agree with the protocol the builder id declares.
+        // Without this, `builder-bugfix-799` adopts the PIR project that happens to
+        // share the number — wrong protocol, wrong porch id, and silently so.
+        //
+        // And when the id is not in canonical form there IS no protocol to
+        // corroborate against, so the claim cannot be trusted at all. The previous
+        // version's comment said exactly that while the code did the opposite —
+        // `if (expectedProtocol && mismatch) continue` let every weak claim through
+        // whenever `expectedProtocol` was null. A legacy or noncanonical builder
+        // could adopt any historical project sharing its tail.
+        if (!expectedProtocol)
+            continue;
+        if (protocol.toLowerCase() !== expectedProtocol.toLowerCase())
+            continue;
+        weak.push(ctx);
+    }
+    const matches = strong.length > 0 ? strong : weak;
+    if (matches.length === 0)
+        return null;
+    if (matches.length > 1) {
+        // Never pick one arbitrarily — that is the bug this whole function exists to
+        // fix, and picking the "least wrong" of several is the same mistake with
+        // better manners.
+        throw new ContextResolutionError(`Ambiguous porch project for '${identity.builderId}': ${matches
+            .map(m => `${m.projectName} (${m.protocol})`)
+            .join(', ')} all claim it. Refusing to guess which one governs this builder.`);
+    }
+    return matches[0];
+}
+/** Read a top-level scalar from porch's status.yaml, stripping quotes. */
+function matchScalar(content, key) {
+    const m = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+    if (!m)
+        return null;
+    const raw = m[1].trim().replace(/^['"]|['"]$/g, '');
+    return raw === '' ? null : raw;
+}
+/**
+ * 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 function protocolFromStatus(fs, worktree, identity) {
+    return readPorchContext(fs, worktree, identity)?.protocol ?? null;
+}
+// ============================================================================
+// Mode
+// ============================================================================
+/**
+ * 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 function modeFromBuilderPrompt(fs, worktree) {
+    const content = fs.read(join(worktree, '.builder-prompt.txt'));
+    if (content === null)
+        return null;
+    const m = content.match(/^##\s*Mode:\s*(STRICT|SOFT)\s*$/im);
+    if (!m)
+        return null;
+    return m[1].toLowerCase();
+}
+/**
+ * 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 function issueNumberFromPorchId(projectId) {
+    if (!projectId)
+        return undefined;
+    if (/^\d+$/.test(projectId))
+        return projectId;
+    const m = projectId.match(/^[a-z]+-(\d+)$/i);
+    return m ? m[1] : undefined;
+}
+// ============================================================================
+// Harness
+// ============================================================================
+/**
+ * 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 function harnessFromLaunchScript(fs, worktree, customHarnesses) {
+    const content = fs.read(join(worktree, '.builder-start.sh'));
+    if (content === null)
+        return null;
+    // Custom names first: a project may define a custom harness whose name
+    // contains a builtin's (e.g. "claude-experimental"), and the more specific
+    // match is the right one.
+    const names = new Set([
+        ...Object.keys(customHarnesses ?? {}),
+        ...Object.keys(BUILTIN_HARNESSES),
+    ]);
+    for (const line of content.split('\n')) {
+        const command = commandNameOf(line);
+        if (command && names.has(command))
+            return command;
+    }
+    return null;
+}
+/**
+ * The command a shell line invokes, or null if the line invokes nothing.
+ *
+ * Matching on **command position** rather than searching the whole line for a
+ * harness name: a substring search would report a false positive on a line like
+ * `if [ "$HARNESS" = "codex" ]`, and naming the wrong harness would either refuse
+ * a resettable builder or — worse — approve typing into one that cannot be reset.
+ */
+function commandNameOf(line) {
+    let rest = line.trim();
+    if (!rest || rest.startsWith('#'))
+        return null;
+    // Strip shell control keywords that can prefix a command on the same line.
+    rest = rest.replace(/^(?:while|until|if|then|else|elif|do|done|fi|exec|command|nohup)\s+/, '');
+    // Strip leading `VAR=value ` environment assignments.
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(rest)) {
+        const space = rest.indexOf(' ');
+        if (space === -1)
+            return null; // a bare assignment invokes nothing
+        rest = rest.slice(space + 1).trimStart();
+    }
+    const first = rest.split(/\s+/)[0];
+    if (!first || first.includes('='))
+        return null;
+    // Basename, so `/usr/local/bin/claude` resolves like `claude`, with any
+    // surrounding quotes removed.
+    const base = first.replace(/^['"]|['"]$/g, '').split('/').pop();
+    return base && base !== '' ? base : 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 function harnessProviderFor(harnessName, customHarnesses) {
+    // Own-property lookup (see getBuiltinHarness): `harnessName` comes from a running
+    // builder's launch script — a user-controlled key — so a bare index could hand
+    // back an inherited Object member as a bogus provider.
+    const builtin = getBuiltinHarness(harnessName);
+    if (builtin)
+        return builtin;
+    if (customHarnesses && harnessName in customHarnesses) {
+        return buildCustomHarnessProvider(customHarnesses[harnessName]);
+    }
+    return 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 function artifactPaths(fs, worktree, porch) {
+    if (!porch)
+        return { specName: null, specPath: null, planPath: null };
+    const specName = porch.projectName;
+    const specRel = join('codev', 'specs', `${specName}.md`);
+    const planRel = join('codev', 'plans', `${specName}.md`);
+    return {
+        specName,
+        specPath: fs.exists(join(worktree, specRel)) ? specRel : null,
+        planPath: fs.exists(join(worktree, planRel)) ? planRel : null,
+    };
+}
+/**
+ * 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 function resolveBuilderContext(options) {
+    const { fs, builderId, worktree, branch, issueNumber, taskText, modeOverride, customHarnesses } = options;
+    if (!fs.exists(worktree)) {
+        throw new ContextResolutionError(`Worktree not found for '${builderId}': ${worktree}. The builder's registry row may be stale.`);
+    }
+    // Resolved once, with identity, and reused for both the protocol chain and
+    // the result. Two independent scans could disagree about which project is
+    // this builder's — the exact ambiguity the identity match exists to remove.
+    const identity = { builderId, issueNumber };
+    const porch = readPorchContext(fs, worktree, identity);
+    // --- Protocol: status.yaml → builder id → abort -------------------------
+    let protocol = porch?.protocol ?? null;
+    let protocolSource = 'status.yaml';
+    if (!protocol) {
+        const parsed = parseAgentName(builderId);
+        if (parsed) {
+            protocol = parsed.protocol;
+            protocolSource = 'builder-id';
+        }
+    }
+    if (!protocol) {
+        throw new ContextResolutionError(`Cannot determine the protocol for '${builderId}': no porch status.yaml under ${worktree}/codev/projects, ` +
+            `and the builder id is not in canonical 'builder-<protocol>-<id>' form. ` +
+            `Refusing to re-orient a builder without naming its protocol.`);
+    }
+    // --- Mode: flag → .builder-prompt.txt → abort ---------------------------
+    const promptMode = modeFromBuilderPrompt(fs, worktree);
+    // Positive evidence, not a negative inference: a bare `--task` spawn writes a
+    // prompt with no `## Mode:` heading, while `--task --protocol X` renders the
+    // full template (built BEFORE porch init, so it survives a failed init).
+    const isBareTask = Boolean(taskText) && promptMode === null;
+    let mode = modeOverride ?? null;
+    let modeSource = 'flag';
+    if (!mode) {
+        mode = promptMode;
+        modeSource = 'builder-prompt';
+    }
+    if (!mode && isBareTask) {
+        // A `--task` spawn writes a bare prompt with no `## Mode:` heading, so this
+        // lane could never auto-detect and every `afx refresh <task>` hard-errored.
+        //
+        // Defaulting to SOFT is not a guess dressed up as a fact: "strict" means
+        // *porch orchestrates this builder*, and a builder with no porch project
+        // cannot be strict. The source is recorded as `task-default` so the report
+        // says where it came from rather than implying the worktree stated it.
+        //
+        // Scoped deliberately to the no-porch case. A porch-driven builder missing
+        // its `## Mode:` line is a genuine ambiguity and still aborts below.
+        mode = 'soft';
+        modeSource = 'task-default';
+    }
+    if (!mode) {
+        throw new ContextResolutionError(`Cannot determine the mode (strict/soft) for '${builderId}': no '## Mode:' line in ` +
+            `${join(worktree, '.builder-prompt.txt')}, and this builder is not the bare ad-hoc-task ` +
+            `lane that defaults to soft (no task text, or a rendered protocol template). ` +
+            `Mode is not persisted anywhere else — pass --mode strict or --mode soft explicitly.`);
+    }
+    // --- Harness: .builder-start.sh → provider → capability check → abort ---
+    const harnessName = harnessFromLaunchScript(fs, worktree, customHarnesses);
+    if (!harnessName) {
+        throw new ContextResolutionError(`Cannot determine the harness for '${builderId}': no recognisable launch command in ` +
+            `${join(worktree, '.builder-start.sh')}. Refusing to type into a terminal whose agent is unknown.`);
+    }
+    const harness = harnessProviderFor(harnessName, customHarnesses);
+    if (!harness) {
+        throw new ContextResolutionError(`Harness '${harnessName}' is not a known provider — it is neither built in nor defined under ` +
+            `"harness" in .codev/config.json. Refusing to type into a terminal whose agent is unknown.`);
+    }
+    if (!harness.supportsContextReset) {
+        throw new ContextResolutionError(`Harness '${harnessName}' has no in-session context reset, so 'afx refresh' cannot clear this ` +
+            `builder's context. Only the claude harness supports it today. ` +
+            `To give this builder a fresh window, stop it and respawn without --resume.`);
+    }
+    const { specName, specPath, planPath } = artifactPaths(fs, worktree, porch);
+    return {
+        builderId,
+        worktree,
+        branch,
+        protocol,
+        protocolSource,
+        mode,
+        modeSource,
+        harnessName,
+        harness,
+        porch,
+        specName,
+        specPath,
+        planPath,
+        // Issue-driven protocols name the porch project after the issue, so the
+        // project id is the correct value when the registry row has none — but ONLY
+        // when it is actually an issue number. The `--task --protocol` lane's porch
+        // id is `builder-task-<id>`, which would render `- Issue: #builder-task-abc`
+        // and an unfollowable `gh issue view builder-task-abc` in the
+        // re-orientation. A fabricated issue reference is worse than none: it sends
+        // a freshly-reset builder to look up requirements that do not exist.
+        issueNumber: issueNumber ?? issueNumberFromPorchId(porch?.projectId),
+        taskText,
+        isBareTask,
+    };
+}
+//# sourceMappingURL=context.js.map

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

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

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

@@ -0,0 +1,192 @@
+/**
+ * Reset orchestrator — the `afx refresh` state machine (Spec 1273).
+ *
+ * Composes the verified parts from phases 1–5 into the flow the architect ran by
+ * hand on 2026-07-27: request save-state → verify the receipt → wait for the
+ * turn to end → `/clear` → re-orient.
+ *
+ * ## Why this is a state machine over injected ports
+ *
+ * Reset is destructive in a way almost nothing else in Agent Farm is: `/clear`
+ * discards a builder's entire conversation, and there is no undo. Every safety
+ * property is therefore an ORDERING property — "the clear never happens before
+ * X" — and ordering is exactly what is hardest to prove by reading code.
+ *
+ * So the orchestrator does two things no ordinary command does:
+ *
+ *   1. Every externally-visible action goes through a port (`clock`, `fs`,
+ *      `sendMessage`, `sendRaw`, `sendEscape`). Nothing here touches Tower, a
+ *      PTY or the filesystem directly.
+ *   2. Every action is appended to an ordered **step log** before it is
+ *      performed.
+ *
+ * The invariant tests then assert over that log — that `clear` never appears
+ * without `assemble` before it, that `escalate-esc` never precedes
+ * `receipt-accepted`, that an aborted run contains no `clear` at all. That turns
+ * "impossible by construction" from a claim in a comment into something a test
+ * can fail on.
+ *
+ * ## The invariants, and where each is enforced
+ *
+ * - **R1** (never clear without a saved re-orientation): `runReset` assembles and
+ *   writes `.builder-reorient.md` at step 2, before any destructive step exists
+ *   in the log. Assembly failure returns before the request is even sent.
+ * - **R2** (never clear without a verified receipt): the poll loop only leaves
+ *   `awaiting-receipt` on `accepted`; every other exit path returns an aborted
+ *   result.
+ * - **R3** (complete-or-abort re-orientation): delegated wholesale to
+ *   `assembleReorientation`, which throws rather than emitting a partial frame.
+ * - **R4** (never clear a builder mid-turn): quiescence is a bounded wait, then
+ *   at most ONE ESC escalation, then a second bounded wait. Still not quiet
+ *   aborts — there is deliberately no third attempt and no "clear anyway".
+ */
+import type { ResolvedBuilderContext } from './context.js';
+import { type IssuePayload, type ReorientationPayload, type ResumeNoticePort, type SpawnPromptPort } from './reorient.js';
+import { type ReceiptFsPort } from './receipt.js';
+/** Filesystem surface. Superset of the receipt gate's, plus the R1 write. */
+export interface ResetFsPort extends ReceiptFsPort {
+    write(path: string, content: string): void;
+}
+/** Wall clock and sleep, injected so tests run instantly and deterministically. */
+export interface ClockPort {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/** What the orchestrator can observe about the target terminal. */
+export interface TerminalObservation {
+    exists: boolean;
+    /**
+     * Epoch ms of the last PTY output (phase 2).
+     *
+     * `undefined` means the Tower serving this terminal predates the field — NOT
+     * "no output ever". The quiescence gate refuses to proceed on `undefined`
+     * rather than treating it as 0, which would read as "silent since 1970" and
+     * clear a builder mid-turn. That is the exact R4 violation this field exists
+     * to prevent.
+     */
+    lastDataAt?: number;
+    /**
+     * Whether input can actually reach the process right now.
+     *
+     * `undefined` means an older Tower did not report it. Unlike `lastDataAt`,
+     * absence here is NOT treated as a refusal, and the asymmetry is deliberate:
+     * an unobservable turn state leads to a SILENT, destructive failure (clearing
+     * a builder mid-turn), whereas an unobservable write path leads to a LOUD,
+     * harmless one (the first send throws). Refuse only what fails quietly.
+     */
+    writable?: boolean;
+}
+/**
+ * The three ways to reach a terminal, kept as three distinct operations.
+ *
+ * They are separate methods rather than one `write(data, mode)` because the
+ * underlying transports are genuinely different and confusing two of them is
+ * silent. Tower's `escape` route calls `writeEscapeToSession`, which writes a
+ * hardcoded ESC and **ignores the message body entirely**
+ * (`servers/message-write.ts:46`). So a single `writeRaw(data)` bound to
+ * `escape: true` would deliver an ESC when asked to type `/clear` — the command
+ * would appear to succeed, the terminal would go quiet, and no context would be
+ * cleared. Splitting the port makes that mistake unrepresentable.
+ */
+export interface TerminalPort {
+    observe(): Promise<TerminalObservation>;
+    /** Deliver a normal, formatted message (the save request, the re-orientation). */
+    sendMessage(message: string): Promise<void>;
+    /**
+     * Type unformatted text into the PTY (Tower's `raw: true`).
+     *
+     * This is how `/clear` is delivered — as literal typed input, which is what
+     * the verified manual recipe used (`afx send <builder> --raw '/clear'`).
+     */
+    sendRaw(text: string): Promise<void>;
+    /** Send a bare ESC keystroke (Tower's `escape: true`; phase 1's path). */
+    sendEscape(): Promise<void>;
+    /**
+     * Recent terminal output plus the buffer's total line count, for best-effort
+     * clear confirmation. Null when this Tower cannot serve it.
+     *
+     * `total` is what makes confirmation trustworthy. A refresh writes into this
+     * same terminal — the save request, the re-orientation — so any pattern matched
+     * against the whole buffer eventually collides with its OWN text. (It did,
+     * twice: first the echoed `/clear`, then the save request's header, which read
+     * "CONTEXT RESET INCOMING" before #1489.) Snapshotting `total` before the clear
+     * lets the check read only what the harness emitted AFTERWARDS.
+     */
+    readOutput?(): Promise<{
+        lines: string[];
+        total: number;
+    } | null>;
+}
+/**
+ * Every externally-visible action, in order.
+ *
+ * The names are part of the test contract — the invariant assertions match on
+ * them — so renaming one is an API change, not a cosmetic edit.
+ */
+export type ResetStepName = 'resolve' | 'assemble' | 'write-reorient-file' | 'interrupt-first' | 'send-save-request' | 'receipt-accepted' | 'quiescent' | 'escalate-esc' | 'clear' | 'clear-confirmed' | 'clear-unconfirmed' | 'send-reorientation';
+export interface ResetStep {
+    name: ResetStepName;
+    at: number;
+    detail?: string;
+}
+export type ResetOutcome = 'completed' | 'aborted' | 'dry-run';
+export interface ResetResult {
+    outcome: ResetOutcome;
+    steps: ResetStep[];
+    /** Populated on `aborted`. Names the gate that failed, never just "failed". */
+    abortReason?: string;
+    nonce: string;
+    statePath: string;
+    reorientPath: string;
+    payload?: ReorientationPayload;
+    /**
+     * The exact save-state request the builder is asked to act on.
+     *
+     * Exposed rather than kept internal because `--dry-run` must be able to print
+     * it. The request is what the whole R2 gate is verifying compliance with, so
+     * "what exactly will the builder be told to write" is the single most useful
+     * thing a dry run can show — and it cannot be shown if the orchestrator keeps
+     * it to itself.
+     */
+    saveRequest: string;
+    /** Size of the accepted state file, for the report. */
+    stateBytes?: number;
+}
+/** Thrown for conditions that must stop the run before anything is touched. */
+export declare class ResetPreflightError extends Error {
+    constructor(message: string);
+}
+export interface RunResetOptions {
+    context: ResolvedBuilderContext;
+    fs: ResetFsPort;
+    clock: ClockPort;
+    terminal: TerminalPort;
+    buildSpawnPrompt: SpawnPromptPort;
+    buildResumeNotice?: ResumeNoticePort;
+    issue?: IssuePayload;
+    /** Architect addendum from `--note` / `--file`. */
+    addendum?: string;
+    /** Print the plan and touch nothing. */
+    dryRun?: boolean;
+    /** ESC before the save request, for a builder already wedged mid-turn. */
+    interruptFirst?: boolean;
+    receiptTimeoutMs?: number;
+    pollIntervalMs?: number;
+    minBytes?: number;
+    stabilityWindowMs?: number;
+    quietWindowMs?: number;
+    quiesceTimeoutMs?: number;
+    quiescePostEscalationTimeoutMs?: number;
+    /** Override for the state-file name. Validated to stay inside the worktree. */
+    stateFileName?: string;
+}
+export declare function runReset(options: RunResetOptions): Promise<ResetResult>;
+/**
+ * Render the step log as the run report.
+ *
+ * Each line carries its EVIDENCE, not just a tick. "Receipt accepted" alone is
+ * the kind of reassurance that hides a stale file; "accepted — 8,432 bytes
+ * carrying nonce a1b2c3" is checkable.
+ */
+export declare function formatResetReport(result: ResetResult): string;
+//# sourceMappingURL=index.d.ts.map

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

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