@cluesmith/codev 3.2.4 → 3.3.1

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

@@ -0,0 +1,149 @@
+/**
+ * The reset receipt gate — invariant R2 (Spec 1273).
+ *
+ * `afx refresh` clears a builder's context, which is irreversible. The manual
+ * version of this flow guarded that step by eyeballing the state file ("ours was
+ * 203 lines"). This module replaces the eyeball with evidence: a state file is
+ * accepted only if it proves it is *this run's* save, is substantive, and has
+ * stopped growing.
+ *
+ * Freshness comes from a nonce written INSIDE the file, not from mtime. mtime
+ * was rejected deliberately: filesystem timestamp granularity and clock skew
+ * make it fragile, and it cannot distinguish "rewritten in response to this
+ * request" from "touched". A nonce the builder must reproduce can only appear
+ * in a file written after the request that carried it.
+ *
+ * Pure: all filesystem access arrives through injected ports, so every rejection
+ * path is testable without a real builder, a real worktree, or real time.
+ */
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { DEFAULT_MIN_BYTES, DEFAULT_STABILITY_WINDOW_MS, STATE_FILE_NAME, } from './constants.js';
+// ============================================================================
+// Nonce
+// ============================================================================
+/**
+ * Generate a per-run nonce.
+ *
+ * Short enough that a builder reproduces it without transcription errors, long
+ * enough that a stale file from a previous reset cannot collide with it.
+ */
+export function generateNonce() {
+    return randomBytes(6).toString('hex');
+}
+/**
+ * The marker line the builder is asked to reproduce verbatim.
+ *
+ * An HTML comment so it is invisible in rendered markdown but trivially
+ * greppable, and harmless if the file is later read by a human.
+ */
+export function nonceMarker(nonce) {
+    return `<!-- codev-reset: ${nonce} -->`;
+}
+// ============================================================================
+// The save-state request
+// ============================================================================
+/**
+ * Build the message asking the builder to write its working state.
+ *
+ * The checklist is the quality bar. It cannot be enforced programmatically (see
+ * `verifyReceipt` — the gate is structural on purpose), so it has to be explicit
+ * enough that a builder writing in good faith produces something a cold reader
+ * can actually use.
+ */
+export function buildSaveRequest(nonce, statePath) {
+    return [
+        'CONTEXT REFRESH INCOMING — save your working state now.',
+        '',
+        `Write your complete working state to \`${statePath}\` (untracked; do not stage or commit it).`,
+        '',
+        `The file MUST begin with this exact line, reproduced character for character:`,
+        '',
+        nonceMarker(nonce),
+        '',
+        'Everything after that line is yours. Write it **for a cold reader** — a competent',
+        'agent who wakes up with your worktree, your branch, and no memory of this',
+        'conversation. Assume nothing carries over. Cover:',
+        '',
+        '1. **Role and mission** — what you are building and why.',
+        '2. **Position in the protocol** — phase, plan phase, what porch expects next.',
+        '3. **Receipts** — what is actually done and verified, with file paths and commit',
+        '   hashes. Distinguish "written" from "verified"; a cold reader cannot tell.',
+        '4. **In-flight work** — anything started but not finished, and where it stands.',
+        '5. **Open questions** — decisions you deferred, and what they hinge on.',
+        '6. **Standing orders** — instructions from the architect you are still bound by,',
+        '   including anything you were told NOT to do.',
+        '7. **Next concrete action** — the single thing to do first after the refresh.',
+        '',
+        'Do not summarise for brevity. A save that omits a standing order or a receipt',
+        'costs more than a long file does. When the file is written, stop and wait.',
+    ].join('\n');
+}
+/**
+ * Evaluate the state file once.
+ *
+ * Checks run in escalating order so the reported reason is the *most specific*
+ * one true: existence, then freshness, then substance, then stability. A caller
+ * polls this and only proceeds on `accepted`.
+ *
+ * Stability requires agreement between two observations separated by at least
+ * `stabilityWindowMs`. Without the time gap, a builder mid-write would look
+ * stable simply because two reads landed between the same two `write()` calls.
+ */
+export function verifyReceipt(options) {
+    const { fs, statePath, nonce, minBytes = DEFAULT_MIN_BYTES, previous = null, msSincePrevious = 0, stabilityWindowMs = DEFAULT_STABILITY_WINDOW_MS, } = options;
+    const bytes = fs.sizeOf(statePath);
+    if (bytes === null)
+        return { status: 'missing' };
+    const content = fs.read(statePath);
+    if (content === null)
+        return { status: 'missing' };
+    // Match on the nonce token rather than the whole marker line: a builder that
+    // reproduces the nonce but alters the comment's spacing has still proved
+    // freshness, and failing that file would discard a real save over whitespace.
+    if (!content.includes(nonce))
+        return { status: 'wrong-nonce', bytes };
+    if (bytes < minBytes)
+        return { status: 'too-small', bytes };
+    const stable = previous !== null &&
+        previous.bytes === bytes &&
+        (previous.status === 'still-growing' || previous.status === 'accepted') &&
+        msSincePrevious >= stabilityWindowMs;
+    if (!stable)
+        return { status: 'still-growing', bytes };
+    return { status: 'accepted', bytes };
+}
+/**
+ * Human-readable explanation of a non-acceptance, for the abort message.
+ *
+ * Reset aborts loudly rather than clearing on a doubtful file, so the architect
+ * needs to know which gate failed — "timed out" alone would not distinguish a
+ * builder that never responded from one that wrote a stub.
+ */
+export function describeReceiptFailure(observation, statePath, minBytes = DEFAULT_MIN_BYTES) {
+    switch (observation.status) {
+        case 'missing':
+            return `${statePath} was never written. The builder may not have read the request (if it is wedged mid-turn, retry with --interrupt-first).`;
+        case 'wrong-nonce':
+            return `${statePath} exists (${observation.bytes} bytes) but does not carry this run's nonce — it is stale, left by an earlier refresh. Refusing to clear on superseded state.`;
+        case 'too-small':
+            return `${statePath} carries the nonce but is only ${observation.bytes} bytes (minimum ${minBytes}). That is a stub, not a working-state save. Override with --min-bytes if this is genuinely all there was.`;
+        case 'still-growing':
+            return `${statePath} was still being written when the wait expired. Refusing to clear on a partial save.`;
+        case 'accepted':
+            return `${statePath} was accepted.`;
+    }
+}
+/**
+ * Absolute path of the state file for a worktree.
+ *
+ * Uses `path.join` rather than string concatenation: this path is handed to the
+ * builder verbatim in the save request, so on Windows a hand-built
+ * `C:\repo\wt\` + `/` + name would instruct the builder to write to a path that
+ * is not the one the gate then stats. `path.join` also collapses redundant
+ * separators, so a trailing slash on the worktree is harmless.
+ */
+export function stateFilePath(worktreePath, fileName = STATE_FILE_NAME) {
+    return join(worktreePath, fileName);
+}
+//# sourceMappingURL=receipt.js.map

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

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

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

@@ -0,0 +1,117 @@
+/**
+ * Re-orientation assembly — invariant R3 (Spec 1273).
+ *
+ * R3: the re-orientation always carries role frame, protocol, mode, project
+ * identity, worktree, branch, the state-file pointer, and — for porch lanes —
+ * the porch re-entry instruction. **There is no code path that emits a partial
+ * frame**: a missing input throws a named error rather than being omitted.
+ *
+ * That strictness is the point. A re-orientation missing its frame does not
+ * crash anything; it produces a builder with a fresh window that does not know
+ * it is a builder, what protocol governs it, or what porch expects next. The
+ * drift is silent and only shows up later as off-protocol work.
+ *
+ * Two parts, with a fixed division:
+ *
+ *   - `inline` — compact, sent as a message. Satisfies R3 on its own. Kept small
+ *     because the message channel writes ≥4-line payloads line-by-line at 10ms
+ *     intervals and multi-line writes risk paste detection (#584).
+ *   - `longForm` — written to `.builder-reorient.md`. This IS the spawn prompt:
+ *     `buildSpawnPrompt` is the same `buildPromptFromTemplate` the fresh-launch
+ *     path calls, so the builder gets the same protocol/phase framing a fresh
+ *     spawn delivers — through a file rather than a prompt argument.
+ *
+ * The role's *full text* is deliberately not inlined. Under the Claude harness it
+ * is injected via `--append-system-prompt`, a process flag that `/clear` does not
+ * touch, so it survives the reset intact. R3 is satisfied by the identity block
+ * regardless, so the guarantee does not rest on that harness detail.
+ */
+import type { ResolvedBuilderContext } from './context.js';
+import type { TemplateContext } from '../spawn-roles.js';
+/**
+ * Renders the protocol's builder prompt. Injected so this module stays pure and
+ * so the orchestrator can wire it to the real `buildPromptFromTemplate`.
+ */
+/**
+ * Renders the porch re-entry guidance. Wired in phase 6 to `buildResumeNotice`,
+ * so reset and spawn share **one** copy of that text.
+ *
+ * Reuse matters beyond tidiness: `buildResumeNotice` carries the fallback
+ * instruction for when porch reports "not found" (run `porch init`). A restated
+ * version drops it, and the two surfaces then drift apart with no test noticing.
+ */
+export type ResumeNoticePort = (projectId: string) => string;
+/**
+ * Typed against the REAL `TemplateContext` rather than a hand-rolled copy.
+ *
+ * The local copy was how issue metadata went missing: the port's shape drifted
+ * from what the templates actually consume, and nothing type-checked the gap.
+ * Importing the canonical type means any field added to `TemplateContext` is
+ * visible here, and a field this module fails to populate is a deliberate
+ * omission rather than an oversight nobody can see.
+ */
+export type SpawnPromptPort = (protocol: string, context: TemplateContext) => string;
+/**
+ * Issue metadata for the spawn template.
+ *
+ * Every issue-driven protocol's builder prompt renders `{{issue.number}}`,
+ * `{{issue.title}}` and `{{issue.body}}` — and for BUGFIX and AIR the issue body
+ * *is* the spec. Omitting it would leave a reset builder on those lanes without
+ * the requirements it is implementing, which is the opposite of spawn-equivalent.
+ *
+ * Fetched by the orchestrator (I/O stays out of this module) and passed in.
+ */
+export interface IssuePayload {
+    number: number | string;
+    title: string;
+    body: string;
+}
+export interface ReorientationPayload {
+    /** Compact frame delivered as a message. Satisfies R3 by itself. */
+    inline: string;
+    /** Full spawn-quality prompt, written to the worktree before the clear (R1). */
+    longForm: string;
+    /** Worktree-relative path the inline frame points at. */
+    longFormFileName: string;
+}
+/** Thrown when a required frame element cannot be produced. Never swallowed. */
+export declare class ReorientationAssemblyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Elements every inline frame must contain, as literal markers.
+ *
+ * Assembly validates the rendered payload against this list before returning, so
+ * adding an element here without producing it fails the tests rather than
+ * silently shipping a frame that is missing it.
+ */
+export declare const REQUIRED_INLINE_MARKERS: readonly ["CONTEXT REFRESH", "You are a Builder", ".builder-role.md", "Protocol:", "Mode:", "Worktree:", "Branch:", "State file:", "Full re-orientation:"];
+/**
+ * Markers required *when the context supplies the corresponding fact*.
+ *
+ * Project identity and porch re-entry are not universally applicable — a task or
+ * shell builder has neither — but on a porch lane they are as load-bearing as
+ * the protocol name, and omitting them would leave a reset builder unable to
+ * find its own project. So they are required conditionally rather than left
+ * optional: "missing input is an abort, not an omission" applies to whatever the
+ * lane actually has.
+ */
+export declare function conditionalInlineMarkers(context: ResolvedBuilderContext): string[];
+export interface AssembleOptions {
+    context: ResolvedBuilderContext;
+    /** Absolute path of the verified state file. */
+    statePath: string;
+    /** Architect addendum from --note / --file. */
+    addendum?: string;
+    buildSpawnPrompt: SpawnPromptPort;
+    /** Porch re-entry guidance; omitted only for non-porch lanes. */
+    buildResumeNotice?: ResumeNoticePort;
+    /**
+     * Issue metadata, when the orchestrator could fetch it. Absence on an
+     * issue-backed lane is surfaced in the long form with a recovery instruction
+     * rather than silently dropped — see `buildLongForm`.
+     */
+    issue?: IssuePayload;
+}
+export declare function assembleReorientation(options: AssembleOptions): ReorientationPayload;
+//# sourceMappingURL=reorient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reorient.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/commands/reset/reorient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD;;;GAGG;AACH;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,MAAM,CAAC;AAErF;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,gFAAgF;AAChF,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,4JAY1B,CAAC;AAEX;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,EAAE,CAOlF;AAMD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,sBAAsB,CAAC;IAChC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,eAAe,CAAC;IAClC,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,oBAAoB,CAoCpF"}

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

@@ -0,0 +1,313 @@
+/**
+ * Re-orientation assembly — invariant R3 (Spec 1273).
+ *
+ * R3: the re-orientation always carries role frame, protocol, mode, project
+ * identity, worktree, branch, the state-file pointer, and — for porch lanes —
+ * the porch re-entry instruction. **There is no code path that emits a partial
+ * frame**: a missing input throws a named error rather than being omitted.
+ *
+ * That strictness is the point. A re-orientation missing its frame does not
+ * crash anything; it produces a builder with a fresh window that does not know
+ * it is a builder, what protocol governs it, or what porch expects next. The
+ * drift is silent and only shows up later as off-protocol work.
+ *
+ * Two parts, with a fixed division:
+ *
+ *   - `inline` — compact, sent as a message. Satisfies R3 on its own. Kept small
+ *     because the message channel writes ≥4-line payloads line-by-line at 10ms
+ *     intervals and multi-line writes risk paste detection (#584).
+ *   - `longForm` — written to `.builder-reorient.md`. This IS the spawn prompt:
+ *     `buildSpawnPrompt` is the same `buildPromptFromTemplate` the fresh-launch
+ *     path calls, so the builder gets the same protocol/phase framing a fresh
+ *     spawn delivers — through a file rather than a prompt argument.
+ *
+ * The role's *full text* is deliberately not inlined. Under the Claude harness it
+ * is injected via `--append-system-prompt`, a process flag that `/clear` does not
+ * touch, so it survives the reset intact. R3 is satisfied by the identity block
+ * regardless, so the guarantee does not rest on that harness detail.
+ */
+import { REORIENT_FILE_NAME } from './constants.js';
+/** Thrown when a required frame element cannot be produced. Never swallowed. */
+export class ReorientationAssemblyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ReorientationAssemblyError';
+    }
+}
+/**
+ * Elements every inline frame must contain, as literal markers.
+ *
+ * Assembly validates the rendered payload against this list before returning, so
+ * adding an element here without producing it fails the tests rather than
+ * silently shipping a frame that is missing it.
+ */
+export const REQUIRED_INLINE_MARKERS = [
+    'CONTEXT REFRESH',
+    'You are a Builder',
+    // The spec requires the identity block to name WHICH role document governs
+    // the builder, not merely that one does.
+    '.builder-role.md',
+    'Protocol:',
+    'Mode:',
+    'Worktree:',
+    'Branch:',
+    'State file:',
+    'Full re-orientation:',
+];
+/**
+ * Markers required *when the context supplies the corresponding fact*.
+ *
+ * Project identity and porch re-entry are not universally applicable — a task or
+ * shell builder has neither — but on a porch lane they are as load-bearing as
+ * the protocol name, and omitting them would leave a reset builder unable to
+ * find its own project. So they are required conditionally rather than left
+ * optional: "missing input is an abort, not an omission" applies to whatever the
+ * lane actually has.
+ */
+export function conditionalInlineMarkers(context) {
+    const markers = [];
+    // Project ID is required, not just the directory stem: porch commands take the
+    // id, and a reset builder should not have to parse it out of a slug.
+    if (context.porch)
+        markers.push('Project ID:', 'Project:', 'porch next');
+    if (context.issueNumber)
+        markers.push('Issue:');
+    return markers;
+}
+export function assembleReorientation(options) {
+    const { context, statePath, addendum, buildSpawnPrompt } = options;
+    requireField(context.builderId, 'builderId');
+    requireField(context.worktree, 'worktree');
+    requireField(context.branch, 'branch');
+    requireField(context.protocol, 'protocol');
+    requireField(context.mode, 'mode');
+    requireField(statePath, 'statePath');
+    // Porch identity is checked field by field, not just for the presence of the
+    // `porch` object. The marker validation below matches on LABELS, so an empty
+    // projectId still renders `Project ID:` and satisfies it — a frame that looks
+    // complete and tells the builder nothing. Presence of a label is not presence
+    // of a value.
+    if (context.porch) {
+        requireField(context.porch.projectId, 'porch.projectId');
+        requireField(context.porch.projectName, 'porch.projectName');
+        requireField(context.porch.phase, 'porch.phase');
+    }
+    const longForm = buildLongForm(options);
+    const inline = buildInline(options);
+    // R3 is enforced here, not asserted in a comment: a frame that lost an element
+    // during a refactor fails at assembly rather than reaching a live builder.
+    const expected = [...REQUIRED_INLINE_MARKERS, ...conditionalInlineMarkers(context)];
+    const missing = expected.filter(marker => !inline.includes(marker));
+    if (missing.length > 0) {
+        throw new ReorientationAssemblyError(`Assembled re-orientation is missing required element(s): ${missing.join(', ')}. ` +
+            `Refusing to clear a builder's context without a complete frame (R3).`);
+    }
+    return { inline, longForm, longFormFileName: REORIENT_FILE_NAME };
+}
+function requireField(value, name) {
+    if (value === undefined || value === null || value === '') {
+        throw new ReorientationAssemblyError(`Cannot assemble a re-orientation without '${name}'. ` +
+            `Refusing to emit a partial frame — a builder re-oriented without it would drift silently (R3).`);
+    }
+}
+// ============================================================================
+// Inline frame
+// ============================================================================
+function buildInline(options) {
+    const { context: c, statePath, addendum } = options;
+    const lines = [
+        '## CONTEXT REFRESH — re-orientation',
+        '',
+        'Your conversation history was cleared. Everything you knew that was not written',
+        'down is gone. Do not try to recall it; read the files below instead.',
+        '',
+        // Name the role document rather than gesturing at it: a builder with no
+        // conversation history cannot resolve "your role document" to a file, and
+        // the spec requires the identity block to say WHICH document governs it.
+        // `.builder-role.md` is the copy the harness actually injected at launch
+        // (written on spawn, and refreshed on resume since #1267 — the clean-exit
+        // relaunch injects it too).
+        'You are a Builder. Your role document is `.builder-role.md` at the worktree root',
+        '(the builder role, injected into your system prompt at spawn and still in effect).',
+        '',
+        `- Protocol: ${c.protocol.toUpperCase()}`,
+        `- Mode: ${c.mode.toUpperCase()}`,
+    ];
+    if (c.issueNumber)
+        lines.push(`- Issue: #${c.issueNumber}`);
+    if (c.porch) {
+        // Project ID is stated explicitly, not left implicit in the directory stem:
+        // `porch status`/`porch next` take the id, and a reset builder should not
+        // have to parse it back out of a slug to address its own project.
+        lines.push(`- Project ID: ${c.porch.projectId}`);
+        lines.push(`- Project: ${c.porch.projectName} (phase: ${c.porch.phase}${c.porch.currentPlanPhase ? `, plan phase: ${c.porch.currentPlanPhase}` : ''})`);
+    }
+    if (c.specPath)
+        lines.push(`- Spec: ${c.specPath}`);
+    if (c.planPath)
+        lines.push(`- Plan: ${c.planPath}`);
+    lines.push(`- Worktree: ${c.worktree}`, `- Branch: ${c.branch}`, '', '### Do this now, in order', '', `1. State file: read \`${statePath}\` **in full** before acting. It is the working`, '   state your previous session wrote for exactly this moment — receipts, open', '   questions, standing orders. Untracked: do not stage or commit it.', `2. Full re-orientation: read \`${REORIENT_FILE_NAME}\` at the worktree root for the`, '   complete protocol framing.');
+    if (c.porch) {
+        // Short pointer inline; the full guidance — including the `porch init`
+        // fallback — is carried verbatim in the long form from buildResumeNotice,
+        // so there is exactly one copy of that text in the codebase.
+        lines.push(`3. Run \`porch next\` to confirm where the protocol actually stands (full re-entry`, `   guidance is in ${REORIENT_FILE_NAME}), and continue.`);
+    }
+    else {
+        lines.push('3. Continue from the next action named in the state file.');
+    }
+    if (addendum && addendum.trim() !== '') {
+        lines.push('', '### From the architect (this post-dates your save)', '', addendum.trim());
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// Long form
+// ============================================================================
+/**
+ * Reconstruct `input_description` (and `task_text`) the way the matching spawn
+ * entry point would.
+ *
+ * `{{input_description}}` is the FIRST line of every protocol's builder prompt
+ * (`bugfix/air/aspir/spir/builder-prompt.md:3`), so getting it wrong mis-frames
+ * the whole document — the reset builder is told it is doing something other
+ * than what it is doing. Spawn produces four distinct values, one per entry
+ * point, and this mirrors all four rather than approximating with two:
+ *
+ *   - spec-driven   → `spawn.ts:455`  (also the lane that attaches an issue)
+ *   - ad-hoc task   → `spawn.ts:543`  (carries `task_text` as well)
+ *   - issue-driven  → `spawn.ts:837`  (BUGFIX/AIR; the issue body IS the spec)
+ *   - protocol-only → `spawn.ts:607`
+ *
+ * **Order is load-bearing, and not the obvious one.** A `--task` builder gets a
+ * porch project keyed on its own builder id, so `issueNumber` is populated for
+ * it too (`context.ts` falls back to `porch.projectId`). Testing `issueNumber`
+ * before `taskText` would therefore route every task builder down the
+ * issue-driven branch and announce a GitHub issue that does not exist. Spec wins
+ * over both because the spec-driven spawn path sets its own description even
+ * when an issue is attached.
+ */
+function buildInputDescription(c) {
+    if (c.specPath)
+        return { input_description: `the feature specified in ${c.specPath}` };
+    if (c.taskText)
+        return { input_description: 'an ad-hoc task', task_text: c.taskText };
+    if (c.issueNumber)
+        return { input_description: `work for GitHub Issue #${c.issueNumber}` };
+    return { input_description: `running the ${c.protocol.toUpperCase()} protocol` };
+}
+function buildLongForm(options) {
+    const { context: c, statePath, addendum, buildSpawnPrompt, buildResumeNotice, issue } = options;
+    let spawnPrompt;
+    // The bare `--task` lane has NO protocol template, and asking for one is not a
+    // near-miss — it is a category error. `afx spawn --task` without `--protocol`
+    // takes spawn.ts's `else` branch and builds the prompt directly from the task
+    // text (`spawn.ts:551`); there is no `protocols/task/builder-prompt.md` to
+    // render, so the live e2e died on
+    // `Protocol "task" has no builder-prompt.md`.
+    //
+    // Identified by a POSITIVE fact rather than by catching that error, and
+    // rather than by `taskText && !porch`: `initPorchInWorktree` is non-fatal, so
+    // a `--task --protocol X` builder whose porch init FAILED also has task text
+    // and no porch. `isBareTask` is established from the prompt file itself (see
+    // context.ts), which carries the rendered template for that lane regardless.
+    if (c.isBareTask) {
+        const longFormTask = [
+            'You are a Builder. Read codev/roles/builder.md for your full role definition.',
+            '',
+            '# Task',
+            '',
+            c.taskText,
+        ].join('\n');
+        return assembleLongFormDocument(options, longFormTask);
+    }
+    try {
+        spawnPrompt = buildSpawnPrompt(c.protocol, {
+            protocol_name: c.protocol.toUpperCase(),
+            mode: c.mode,
+            mode_soft: c.mode === 'soft',
+            mode_strict: c.mode === 'strict',
+            project_id: c.porch?.projectId,
+            ...buildInputDescription(c),
+            ...(c.specPath && c.specName ? { spec: { path: c.specPath, name: c.specName } } : {}),
+            ...(c.planPath && c.specName ? { plan: { path: c.planPath, name: c.specName } } : {}),
+            // Issue-driven protocols render {{issue.*}} in their builder prompt, and
+            // on BUGFIX/AIR the body IS the spec. Forwarding it is what makes the long
+            // form genuinely spawn-equivalent rather than spawn-shaped.
+            ...(issue ? { issue: { number: issue.number, title: issue.title, body: issue.body } } : {}),
+        });
+    }
+    catch (err) {
+        // Abort rather than degrade: a long form without the protocol framing is the
+        // partial frame R3 forbids, and it would be delivered to a builder with no
+        // context left to notice the gap.
+        throw new ReorientationAssemblyError(`Could not render the ${c.protocol} builder prompt for the long-form re-orientation: ` +
+            `${err instanceof Error ? err.message : String(err)}. Refusing to clear without it (R1/R3).`);
+    }
+    return assembleLongFormDocument(options, spawnPrompt);
+}
+/**
+ * Wrap a rendered prompt body in the reset header, state-file pointer, addendum
+ * and porch re-entry.
+ *
+ * Shared by both lanes so the framing cannot drift between them: the bare
+ * `--task` lane supplies spawn's task prompt, every other lane supplies the
+ * rendered protocol template. Only the BODY differs — everything R3 requires is
+ * assembled here, once.
+ */
+function assembleLongFormDocument(options, promptBody) {
+    const { context: c, statePath, addendum, buildResumeNotice, issue } = options;
+    const header = [
+        '<!-- Written by `afx refresh` (Spec 1273). Untracked; regenerated on every refresh. -->',
+        '',
+        '# Re-orientation after context refresh',
+        '',
+        `Your conversation history was cleared deliberately, to give you a fresh window`,
+        `without losing your working state. This file restores the protocol framing a`,
+        `fresh spawn would have given you; \`${statePath}\` holds what your previous`,
+        `session actually knew.`,
+        '',
+        '## Read order',
+        '',
+        `1. \`${statePath}\` — your working state (receipts, open questions, standing orders).`,
+        '2. The rest of this file — protocol framing, identical to a fresh spawn prompt.',
+        c.porch ? '3. `porch next` — the authoritative protocol state.' : '3. The next action named in your state file.',
+        '',
+        '## Current position',
+        '',
+        `- Builder: ${c.builderId}`,
+        `- Protocol: ${c.protocol.toUpperCase()} (${c.mode})`,
+        `- Worktree: ${c.worktree}`,
+        `- Branch: ${c.branch}`,
+    ];
+    if (c.porch) {
+        header.push(`- Porch project ID: ${c.porch.projectId}`, `- Porch project: ${c.porch.projectName}`, `- Phase: ${c.porch.phase}${c.porch.currentPlanPhase ? ` (plan phase: ${c.porch.currentPlanPhase})` : ''}`);
+    }
+    if (c.issueNumber)
+        header.push(`- Issue: #${c.issueNumber}`);
+    header.push('', `Protocol and mode were resolved from ${c.protocolSource} and ${c.modeSource} respectively.`);
+    // An issue-backed lane whose issue could not be fetched keeps a VISIBLE gap
+    // with a recovery instruction, rather than a silently shorter prompt. On
+    // BUGFIX/AIR the issue body is the spec, so a reset builder must be told the
+    // requirements are missing instead of inferring them from what remains.
+    if (c.issueNumber && !issue) {
+        header.push('', `> **Issue #${c.issueNumber} could not be fetched when this file was written**, so the`, `> protocol framing below does not include its title or body. On issue-driven`, `> protocols that body carries the requirements. Read it before continuing:`, `> \`gh issue view ${c.issueNumber}\`.`);
+    }
+    if (addendum && addendum.trim() !== '') {
+        header.push('', '## From the architect (post-dates your save)', '', addendum.trim());
+    }
+    // Porch re-entry, verbatim from the single source shared with spawn. Reset must
+    // not restate it: buildResumeNotice carries the `porch init` fallback for when
+    // porch reports "not found", and a restated copy silently drops it.
+    if (c.porch) {
+        if (!buildResumeNotice) {
+            throw new ReorientationAssemblyError(`Cannot assemble a re-orientation for porch project '${c.porch.projectName}' without the ` +
+                `porch re-entry notice. Refusing to emit a frame that leaves a porch-driven builder ` +
+                `without its re-entry instruction (R3).`);
+        }
+        header.push('', '---', '', buildResumeNotice(c.porch.projectId).trim());
+    }
+    header.push('', '---', '', '## Protocol framing (as delivered at spawn)', '');
+    return `${header.join('\n')}\n${promptBody}\n`;
+}
+//# sourceMappingURL=reorient.js.map

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

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

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

@@ -0,0 +1,34 @@
+/**
+ * `afx refresh` — the command surface over the refresh state machine (Spec 1273).
+ *
+ * This file is deliberately thin. It does three things and nothing else:
+ * resolves the target, binds REAL implementations to the orchestrator's ports,
+ * and prints the report. Every decision, every ordering rule and every refusal
+ * lives in `reset/index.ts`, where it is testable without Tower, a PTY, or a
+ * live builder.
+ *
+ * That split is the point. The dangerous part of a refresh is the ordering, and
+ * ordering is only provable if the thing that decides it has no I/O in it.
+ *
+ * Addressing, workspace detection and sender identity are reused verbatim from
+ * `afx send` — there is exactly one address resolver (the same rule `afx
+ * interrupt` follows).
+ */
+import type { ResetOptions } from '../types.js';
+/**
+ * The one-line notice `afx reset` prints before doing the work (#1489).
+ *
+ * Exported so the deprecation is pinned by a test rather than by whoever
+ * happens to read the CLI wiring: an alias that stops announcing itself is an
+ * alias nobody migrates off, and this one is scheduled for removal.
+ */
+export declare const RESET_ALIAS_NOTICE = "afx reset has been renamed to afx refresh; this alias will be removed in a future release";
+/**
+ * Announce the deprecated spelling on **stderr**.
+ *
+ * stdout carries the run report, which is read by humans and occasionally piped;
+ * a deprecation line does not belong in it.
+ */
+export declare function warnResetAlias(): void;
+export declare function refresh(options: ResetOptions): Promise<void>;
+//# sourceMappingURL=reset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/commands/reset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,8FAC8D,CAAC;AAE9F;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuHlE"}