@cluesmith/codev 3.3.1 → 3.3.2

package/dist/commands/porch/context-refresh.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Context-refresh boundary resolution and task emission (Spec 1470).
+ *
+ * ## What a boundary is, and why it is recorded rather than inferred
+ *
+ * A boundary is a moment porch already transitions the state machine, at which a
+ * builder's context can be discarded without losing anything: the spec, the plan,
+ * `status.yaml`, the thread narrative and git carry the durable state, so a
+ * refreshed builder re-orients from disk rather than from memory.
+ *
+ * The refresh is DESTRUCTIVE — it ends in `/clear`, which has no undo — so it must
+ * fire at most once per boundary. Porch transitions can loop: issue #1408 saw
+ * verify-approval reset every plan phase back to `pending`, which would replay
+ * every plan-phase advance. A side effect that wipes context cannot be guarded by
+ * inferring "we must already have done this" from phase or iteration; it has to be
+ * a RECORDED FACT. That is what `context_refreshes` in `status.yaml` is.
+ *
+ * ## Where at-most-once actually comes from
+ *
+ * Not from a lock or a guard, but from control flow. Each transition site mutates
+ * the phase fields AND appends the boundary record in ONE `writeStateAndCommit`,
+ * then returns the refresh task INSTEAD of recursing into `next()`. The next
+ * `porch next` reads a state where the boundary is already recorded, so
+ * {@link hasRefreshed} is true and the normal path runs. There is no window in
+ * which the record and the transition disagree, because they are the same write.
+ *
+ * ## Failure semantics: consumed means consumed
+ *
+ * The boundary is recorded when the task is EMITTED, not when the refresh
+ * succeeds. A refresh that fails, or that the builder never runs, is never
+ * retried. That is deliberate:
+ *
+ *   - The builder-side command never writes `status.yaml` (only porch does), so
+ *     there is no completion signal to model and no way for a failed refresh to
+ *     corrupt protocol state.
+ *   - A missed refresh costs context and nothing else. A repeated one costs a
+ *     builder's working memory, over and over, with nobody watching.
+ *
+ * Asymmetric costs, so the design fails toward doing nothing.
+ */
+import type { PorchTask, ProjectState, Protocol } from './types.js';
+/**
+ * Identifier for entering a protocol phase.
+ *
+ * Derived from the transition rather than from a configured label, so the record
+ * in `status.yaml` cannot drift from the event that produced it.
+ */
+export declare function enterBoundary(phaseId: string): string;
+/** Identifier for advancing INTO a given plan phase. */
+export declare function planPhaseBoundary(planPhaseId: string): string;
+/**
+ * Is a phase-entry boundary declared for this protocol?
+ *
+ * Inspects the FIELDS, never the presence of the `context_refresh` object.
+ * `context_refresh: {}` is valid and declares nothing, so a truthiness check on
+ * the object would report every boundary as declared for a protocol that opted
+ * into none of them.
+ */
+export declare function declaresEnter(protocol: Protocol, phaseId: string): boolean;
+/** Is the plan-phase-advance boundary declared for this protocol? */
+export declare function declaresPlanPhaseAdvance(protocol: Protocol): boolean;
+/** Has this boundary already been refreshed for this project? */
+export declare function hasRefreshed(state: ProjectState, boundary: string): boolean;
+/**
+ * Record a boundary on the state object.
+ *
+ * Mutates rather than writing: the caller folds this into the SAME
+ * `writeStateAndCommit` as the transition itself, which is what makes the record
+ * and the transition atomic. A separate write here would open exactly the window
+ * this design closes.
+ */
+export declare function recordRefresh(state: ProjectState, boundary: string, now: string): void;
+/**
+ * Mark every recorded boundary as acknowledged, returning true if anything changed.
+ *
+ * ## Why an acknowledgment exists at all
+ *
+ * A refresh is unattended, and its worst failure is silent: the builder clears,
+ * the re-entry never arrives, and nothing ever says so. The plan's first design
+ * tried to DERIVE that from `updated_at` — but the normal task-emission path in
+ * `next()` writes no state, so `updated_at` stays pinned at the transition for
+ * the whole of a healthy build. A threshold long enough to avoid false positives
+ * would be far too long to catch the stall it exists for.
+ *
+ * So porch records the fact instead. This runs on the first `porch next` that
+ * reaches the NORMAL path after a boundary — which only happens if a builder came
+ * back and asked for work. A boundary recorded but never acknowledged therefore
+ * means exactly one thing: nobody returned.
+ *
+ * ## Why porch owns it
+ *
+ * The builder-side command is forbidden from writing `status.yaml`, and that
+ * prohibition is load-bearing — it is what makes a failed refresh incapable of
+ * corrupting protocol state. So the acknowledgment cannot come from the side that
+ * would most naturally report "I'm back"; it has to be inferred by the only
+ * writer, from the only evidence it has: the builder asked for its next task.
+ *
+ * Writes at most once per boundary, so this costs one extra state write per
+ * refresh rather than one per `porch next`.
+ *
+ * ## What this cannot distinguish, and why that is accepted
+ *
+ * Any normal-path pass acknowledges EVERY outstanding boundary. So a refresh
+ * that was refused before clearing — after which the builder simply runs `porch
+ * next` — reads as acknowledged, as does a stall a human recovered by hand.
+ *
+ * That is not a bug to fix here, because porch has exactly one piece of
+ * evidence: the builder asked for work. It cannot tell "cleared and came back"
+ * from "never cleared" from "was rescued", and inventing a distinction it cannot
+ * observe would be worse than admitting the limit. What the signal genuinely
+ * means is narrow and still useful: **no builder has asked for work since this
+ * boundary was recorded.**
+ */
+export declare function acknowledgeRefreshes(state: ProjectState, now: string): boolean;
+/**
+ * How long a refresh may legitimately take before silence means trouble.
+ *
+ * A refresh is not instant: the builder writes a save (minutes, for a real one),
+ * the re-entry is held by Tower for {@link DEFAULT_REENTRY_DELAY_SECONDS}, the
+ * mailbox waits for a clean prompt, and only then does the builder run `porch
+ * next`. Ten minutes is comfortably past all of that and still far sooner than a
+ * human would otherwise notice a builder sitting cleared and idle.
+ */
+export declare const REFRESH_STALL_GRACE_MS: number;
+/**
+ * Boundaries recorded but never acknowledged — the raw fact, no timing applied.
+ *
+ * Use this for HISTORY (what has and has not been acknowledged). For deciding
+ * whether to warn a human, use {@link stalledRefreshes}, which adds the grace
+ * period.
+ */
+export declare function unacknowledgedRefreshes(state: ProjectState): Array<{
+    boundary: string;
+    at: string;
+}>;
+/**
+ * Unacknowledged boundaries old enough that silence is a problem.
+ *
+ * ## Why a grace period after all
+ *
+ * An earlier version of this warned on ANY unacknowledged boundary, with a
+ * comment arguing that time-based rules do not work here. That argument
+ * conflated two different things, and the result was a warning on every healthy
+ * refresh — a false positive during completely normal operation, every single
+ * time.
+ *
+ * What genuinely does not work is deriving the stall from `updated_at`, because
+ * that timestamp does not move during a healthy build. But the ACKNOWLEDGMENT
+ * does move, exactly when the builder returns. Given a reliable event, a grace
+ * period is simply the answer to "has enough time passed that silence is
+ * suspicious?" — which is the question, and which the plan asked for in the
+ * words "past a threshold".
+ *
+ * A signal that fires during normal operation is not a signal.
+ */
+export declare function stalledRefreshes(state: ProjectState, now: number, graceMs?: number): Array<{
+    boundary: string;
+    at: string;
+    ageMs: number;
+}>;
+/**
+ * Should a refresh fire for `boundary`, and is it declared?
+ *
+ * Deliberately does NOT consider how much context the builder has used. The spec
+ * fixes always-fire-at-configured-boundaries over threshold triggering:
+ * thresholds would need harness introspection porch does not have, and would make
+ * the behavior non-deterministic and untestable. An unnecessary refresh at a
+ * clean boundary costs a re-read of artifacts the builder can already see.
+ */
+export declare function shouldRefresh(state: ProjectState, declared: boolean, boundary: string): boolean;
+/**
+ * The single task emitted at a boundary.
+ *
+ * Deliberately does NOT instruct `porch done`. A refresh is not a build: `porch
+ * done` would validate checks and advance the build state, which is wrong at a
+ * moment when nothing was built. The builder refreshes and then re-enters through
+ * `porch next`, which is also what the post-clear re-entry frame says — so both
+ * paths converge on the same next command whether or not the clear lands.
+ */
+export declare function buildRefreshTask(boundary: string): PorchTask;
+//# sourceMappingURL=context-refresh.d.ts.map

package/dist/commands/porch/context-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-refresh.d.ts","sourceRoot":"","sources":["../../../src/commands/porch/context-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAwB,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM1F;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAEpE;AAMD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAItF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAS9E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,GAClB,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAIzC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,MAAM,EACX,OAAO,SAAyB,GAC/B,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAOxD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAET;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA0C5D"}

package/dist/commands/porch/context-refresh.js

@@ -0,0 +1,270 @@
+/**
+ * Context-refresh boundary resolution and task emission (Spec 1470).
+ *
+ * ## What a boundary is, and why it is recorded rather than inferred
+ *
+ * A boundary is a moment porch already transitions the state machine, at which a
+ * builder's context can be discarded without losing anything: the spec, the plan,
+ * `status.yaml`, the thread narrative and git carry the durable state, so a
+ * refreshed builder re-orients from disk rather than from memory.
+ *
+ * The refresh is DESTRUCTIVE — it ends in `/clear`, which has no undo — so it must
+ * fire at most once per boundary. Porch transitions can loop: issue #1408 saw
+ * verify-approval reset every plan phase back to `pending`, which would replay
+ * every plan-phase advance. A side effect that wipes context cannot be guarded by
+ * inferring "we must already have done this" from phase or iteration; it has to be
+ * a RECORDED FACT. That is what `context_refreshes` in `status.yaml` is.
+ *
+ * ## Where at-most-once actually comes from
+ *
+ * Not from a lock or a guard, but from control flow. Each transition site mutates
+ * the phase fields AND appends the boundary record in ONE `writeStateAndCommit`,
+ * then returns the refresh task INSTEAD of recursing into `next()`. The next
+ * `porch next` reads a state where the boundary is already recorded, so
+ * {@link hasRefreshed} is true and the normal path runs. There is no window in
+ * which the record and the transition disagree, because they are the same write.
+ *
+ * ## Failure semantics: consumed means consumed
+ *
+ * The boundary is recorded when the task is EMITTED, not when the refresh
+ * succeeds. A refresh that fails, or that the builder never runs, is never
+ * retried. That is deliberate:
+ *
+ *   - The builder-side command never writes `status.yaml` (only porch does), so
+ *     there is no completion signal to model and no way for a failed refresh to
+ *     corrupt protocol state.
+ *   - A missed refresh costs context and nothing else. A repeated one costs a
+ *     builder's working memory, over and over, with nobody watching.
+ *
+ * Asymmetric costs, so the design fails toward doing nothing.
+ */
+import { selfRefreshInvocation } from '../../lib/self-refresh-invocation.js';
+// ============================================================================
+// Boundary identifiers
+// ============================================================================
+/**
+ * Identifier for entering a protocol phase.
+ *
+ * Derived from the transition rather than from a configured label, so the record
+ * in `status.yaml` cannot drift from the event that produced it.
+ */
+export function enterBoundary(phaseId) {
+    return `enter:${phaseId}`;
+}
+/** Identifier for advancing INTO a given plan phase. */
+export function planPhaseBoundary(planPhaseId) {
+    return `plan-phase:${planPhaseId}`;
+}
+// ============================================================================
+// Declaration lookup
+// ============================================================================
+/**
+ * Is a phase-entry boundary declared for this protocol?
+ *
+ * Inspects the FIELDS, never the presence of the `context_refresh` object.
+ * `context_refresh: {}` is valid and declares nothing, so a truthiness check on
+ * the object would report every boundary as declared for a protocol that opted
+ * into none of them.
+ */
+export function declaresEnter(protocol, phaseId) {
+    const config = protocol.context_refresh;
+    return Array.isArray(config?.on_enter) && config.on_enter.includes(phaseId);
+}
+/** Is the plan-phase-advance boundary declared for this protocol? */
+export function declaresPlanPhaseAdvance(protocol) {
+    return protocol.context_refresh?.on_plan_phase_advance === true;
+}
+// ============================================================================
+// The record
+// ============================================================================
+/** Has this boundary already been refreshed for this project? */
+export function hasRefreshed(state, boundary) {
+    return (state.context_refreshes ?? []).some(r => r.boundary === boundary);
+}
+/**
+ * Record a boundary on the state object.
+ *
+ * Mutates rather than writing: the caller folds this into the SAME
+ * `writeStateAndCommit` as the transition itself, which is what makes the record
+ * and the transition atomic. A separate write here would open exactly the window
+ * this design closes.
+ */
+export function recordRefresh(state, boundary, now) {
+    if (!state.context_refreshes)
+        state.context_refreshes = [];
+    if (hasRefreshed(state, boundary))
+        return;
+    state.context_refreshes.push({ boundary, at: now });
+}
+/**
+ * Mark every recorded boundary as acknowledged, returning true if anything changed.
+ *
+ * ## Why an acknowledgment exists at all
+ *
+ * A refresh is unattended, and its worst failure is silent: the builder clears,
+ * the re-entry never arrives, and nothing ever says so. The plan's first design
+ * tried to DERIVE that from `updated_at` — but the normal task-emission path in
+ * `next()` writes no state, so `updated_at` stays pinned at the transition for
+ * the whole of a healthy build. A threshold long enough to avoid false positives
+ * would be far too long to catch the stall it exists for.
+ *
+ * So porch records the fact instead. This runs on the first `porch next` that
+ * reaches the NORMAL path after a boundary — which only happens if a builder came
+ * back and asked for work. A boundary recorded but never acknowledged therefore
+ * means exactly one thing: nobody returned.
+ *
+ * ## Why porch owns it
+ *
+ * The builder-side command is forbidden from writing `status.yaml`, and that
+ * prohibition is load-bearing — it is what makes a failed refresh incapable of
+ * corrupting protocol state. So the acknowledgment cannot come from the side that
+ * would most naturally report "I'm back"; it has to be inferred by the only
+ * writer, from the only evidence it has: the builder asked for its next task.
+ *
+ * Writes at most once per boundary, so this costs one extra state write per
+ * refresh rather than one per `porch next`.
+ *
+ * ## What this cannot distinguish, and why that is accepted
+ *
+ * Any normal-path pass acknowledges EVERY outstanding boundary. So a refresh
+ * that was refused before clearing — after which the builder simply runs `porch
+ * next` — reads as acknowledged, as does a stall a human recovered by hand.
+ *
+ * That is not a bug to fix here, because porch has exactly one piece of
+ * evidence: the builder asked for work. It cannot tell "cleared and came back"
+ * from "never cleared" from "was rescued", and inventing a distinction it cannot
+ * observe would be worse than admitting the limit. What the signal genuinely
+ * means is narrow and still useful: **no builder has asked for work since this
+ * boundary was recorded.**
+ */
+export function acknowledgeRefreshes(state, now) {
+    let changed = false;
+    for (const record of state.context_refreshes ?? []) {
+        if (record.acknowledged_at === undefined) {
+            record.acknowledged_at = now;
+            changed = true;
+        }
+    }
+    return changed;
+}
+/**
+ * How long a refresh may legitimately take before silence means trouble.
+ *
+ * A refresh is not instant: the builder writes a save (minutes, for a real one),
+ * the re-entry is held by Tower for {@link DEFAULT_REENTRY_DELAY_SECONDS}, the
+ * mailbox waits for a clean prompt, and only then does the builder run `porch
+ * next`. Ten minutes is comfortably past all of that and still far sooner than a
+ * human would otherwise notice a builder sitting cleared and idle.
+ */
+export const REFRESH_STALL_GRACE_MS = 10 * 60 * 1000;
+/**
+ * Boundaries recorded but never acknowledged — the raw fact, no timing applied.
+ *
+ * Use this for HISTORY (what has and has not been acknowledged). For deciding
+ * whether to warn a human, use {@link stalledRefreshes}, which adds the grace
+ * period.
+ */
+export function unacknowledgedRefreshes(state) {
+    return (state.context_refreshes ?? [])
+        .filter(r => r.acknowledged_at === undefined)
+        .map(r => ({ boundary: r.boundary, at: r.at }));
+}
+/**
+ * Unacknowledged boundaries old enough that silence is a problem.
+ *
+ * ## Why a grace period after all
+ *
+ * An earlier version of this warned on ANY unacknowledged boundary, with a
+ * comment arguing that time-based rules do not work here. That argument
+ * conflated two different things, and the result was a warning on every healthy
+ * refresh — a false positive during completely normal operation, every single
+ * time.
+ *
+ * What genuinely does not work is deriving the stall from `updated_at`, because
+ * that timestamp does not move during a healthy build. But the ACKNOWLEDGMENT
+ * does move, exactly when the builder returns. Given a reliable event, a grace
+ * period is simply the answer to "has enough time passed that silence is
+ * suspicious?" — which is the question, and which the plan asked for in the
+ * words "past a threshold".
+ *
+ * A signal that fires during normal operation is not a signal.
+ */
+export function stalledRefreshes(state, now, graceMs = REFRESH_STALL_GRACE_MS) {
+    return unacknowledgedRefreshes(state)
+        .map(r => ({ ...r, ageMs: now - Date.parse(r.at) }))
+        // An unparseable timestamp yields NaN, and every NaN comparison is false —
+        // so it would never warn. Treat it as stalled rather than silently ignoring
+        // it: a record we cannot age is a record we cannot vouch for.
+        .filter(r => Number.isNaN(r.ageMs) || r.ageMs >= graceMs);
+}
+// ============================================================================
+// Decision
+// ============================================================================
+/**
+ * Should a refresh fire for `boundary`, and is it declared?
+ *
+ * Deliberately does NOT consider how much context the builder has used. The spec
+ * fixes always-fire-at-configured-boundaries over threshold triggering:
+ * thresholds would need harness introspection porch does not have, and would make
+ * the behavior non-deterministic and untestable. An unnecessary refresh at a
+ * clean boundary costs a re-read of artifacts the builder can already see.
+ */
+export function shouldRefresh(state, declared, boundary) {
+    return declared && !hasRefreshed(state, boundary);
+}
+// ============================================================================
+// The task
+// ============================================================================
+/**
+ * The single task emitted at a boundary.
+ *
+ * Deliberately does NOT instruct `porch done`. A refresh is not a build: `porch
+ * done` would validate checks and advance the build state, which is wrong at a
+ * moment when nothing was built. The builder refreshes and then re-enters through
+ * `porch next`, which is also what the post-clear re-entry frame says — so both
+ * paths converge on the same next command whether or not the clear lands.
+ */
+export function buildRefreshTask(boundary) {
+    // Single source: see `lib/self-refresh-invocation.ts` for why this is not
+    // typed out here. Two hand-written copies have already dropped the flag.
+    const invocation = selfRefreshInvocation(boundary);
+    return {
+        subject: 'Refresh your context',
+        activeForm: 'Refreshing context',
+        description: [
+            `CONTEXT REFRESH BOUNDARY: \`${boundary}\``,
+            '',
+            'You have reached a protocol boundary where your context can be safely refreshed.',
+            'Your durable state is already on disk — the spec, the plan, `status.yaml`, your',
+            'thread narrative and git history — so a fresh context re-orients from artifacts',
+            'rather than from memory.',
+            '',
+            'Run the builder-refresh procedure:',
+            '',
+            '```bash',
+            `${invocation.begin}   # issue the challenge`,
+            '# ...write your working state to the file it names...',
+            `${invocation.execute}   # verify, then clear and re-orient`,
+            '```',
+            '',
+            'Pass `--boundary` on BOTH commands. It binds the challenge to this boundary, so a',
+            'challenge left behind by an aborted refresh cannot be used to clear you at a later',
+            'one — against a save describing work that has since moved on.',
+            '',
+            'If your harness provides the `/builder-refresh` skill, invoke that instead — it',
+            'sequences the same steps.',
+            '',
+            'IMPORTANT:',
+            `- This boundary is already recorded in \`status.yaml\`. It will NOT fire again,`,
+            '  whether the refresh succeeds or fails.',
+            '- Do NOT run `porch done` for this task. A refresh is not a build.',
+            '- If the refresh REFUSES (it fails safe rather than clearing on an unverified',
+            '  save), you keep your context. Report the refusal to the architect with',
+            '  `afx send architect "..."` and continue — run `porch next` for your normal tasks.',
+            '- After a successful refresh your next instruction arrives automatically. It will',
+            '  tell you to run `porch next`.',
+        ].join('\n'),
+        sequential: true,
+    };
+}
+//# sourceMappingURL=context-refresh.js.map

package/dist/commands/porch/context-refresh.js.map

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

package/dist/commands/porch/index.d.ts

@@ -27,6 +27,12 @@ import { type ArtifactResolver } from './artifacts.js';
  *     "gate_requested_at": string | null,   // ISO timestamp
  *     "gate_approved_at": string | null     // ISO timestamp
  *   }
+ *
+ * `--json` also carries the Spec 1470 refresh fields: `context_refreshes` (the
+ * full history, each with `boundary`, `at`, and `acknowledged_at` once a builder
+ * has returned), `unacknowledged_refreshes` (the raw fact, any age), and
+ * `stalled_refreshes` (only those past the grace period, each with `ageMs`).
+ * Fields are ADDED; nothing pre-existing is removed or retyped.
  */
 export declare function status(workspaceRoot: string, projectId: string, resolver?: ArtifactResolver, options?: {
     json?: boolean;

package/dist/commands/porch/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/porch/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqCH,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAiFnF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,MAAM,CAC1B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsHf;AAED;;;GAGG;AACH,wBAAsB,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDhH;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+L5K;AAsED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyD/G;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,OAAO,EACrB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Hf;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA+Ef;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACxB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AA0CD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ElE;AAoBD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6KvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/porch/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsCH,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAiFnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,MAAM,CAC1B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAqKf;AAED;;;GAGG;AACH,wBAAsB,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDhH;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+L5K;AAsED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyD/G;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,OAAO,EACrB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Hf;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA+Ef;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACxB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AA0CD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0ElE;AAoBD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6KvD"}

package/dist/commands/porch/index.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import chalk from 'chalk';
 import { globSync } from 'glob';
+import { stalledRefreshes, unacknowledgedRefreshes } from './context-refresh.js';
 import { readState, writeStateAndCommit, createInitialState, findStatusPath, getArtifactRoot, getProjectDir, getStatusPath, resolveProjectId, resolveArtifactBaseName, } from './state.js';
 import { loadProtocol, getPhaseConfig, getNextPhase, getPhaseChecks, getPhaseGate, isPhased, isBuildVerify, getVerifyConfig, } from './protocol.js';
 import { findPlanFile, extractPlanPhases, getCurrentPlanPhase, getPhaseContent, allPlanPhasesComplete, } from './plan.js';
@@ -99,6 +100,12 @@ function logCheckOverrides(phaseCheckNames, resolvedChecks, overrides) {
  *     "gate_requested_at": string | null,   // ISO timestamp
  *     "gate_approved_at": string | null     // ISO timestamp
  *   }
+ *
+ * `--json` also carries the Spec 1470 refresh fields: `context_refreshes` (the
+ * full history, each with `boundary`, `at`, and `acknowledged_at` once a builder
+ * has returned), `unacknowledged_refreshes` (the raw fact, any age), and
+ * `stalled_refreshes` (only those past the grace period, each with `ageMs`).
+ * Fields are ADDED; nothing pre-existing is removed or retyped.
  */
 export async function status(workspaceRoot, projectId, resolver, options) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
@@ -126,6 +133,11 @@ export async function status(workspaceRoot, projectId, resolver, options) {
             gate_status: gateStatus?.status ?? null,
             gate_requested_at: gateStatus?.requested_at ?? null,
             gate_approved_at: gateStatus?.approved_at ?? null,
+            // Spec 1470. Fields ADDED, none removed or retyped, so existing consumers
+            // (dashboard, VS Code tree) keep parsing unchanged.
+            context_refreshes: state.context_refreshes ?? [],
+            unacknowledged_refreshes: unacknowledgedRefreshes(state),
+            stalled_refreshes: stalledRefreshes(state, Date.now()),
         };
         process.stdout.write(JSON.stringify(out) + '\n');
         return;
@@ -156,6 +168,40 @@ export async function status(workspaceRoot, projectId, resolver, options) {
             const title = isCurrent ? chalk.bold(phase.title) : phase.title;
             console.log(`${prefix}${icon(phase.status)} ${phase.id}: ${title}`);
         }
+    }
+    // Context refreshes (Spec 1470). Shown for any protocol that has them, not
+    // only phased ones — a boundary can fire on entering `plan` too.
+    const refreshes = state.context_refreshes ?? [];
+    if (refreshes.length > 0) {
+        const stalled = stalledRefreshes(state, Date.now());
+        console.log('');
+        console.log(chalk.bold('CONTEXT REFRESHES:'));
+        console.log('');
+        for (const r of refreshes) {
+            const done = r.acknowledged_at !== undefined;
+            const isStalled = stalled.some(sr => sr.boundary === r.boundary);
+            // Three states, not two: acknowledged, in flight, and stalled. Marking an
+            // in-flight refresh as a fault would cry wolf on every healthy one.
+            const mark = done ? chalk.green('✓') : isStalled ? chalk.yellow('!') : chalk.cyan('…');
+            const when = done
+                ? ''
+                : isStalled
+                    ? chalk.yellow('  ← no builder has returned since')
+                    : chalk.cyan('  ← refresh in flight');
+            console.log(`  ${mark} ${r.boundary}  ${chalk.gray(r.at)}${when}`);
+        }
+        if (stalled.length > 0) {
+            // The unattended failure this whole field exists to surface: the builder
+            // cleared and nothing came back. Say what to do, because the person
+            // reading this is not necessarily the person who built the feature.
+            console.log('');
+            console.log(chalk.yellow(`  ⚠ ${stalled.length} refresh(es) recorded but never acknowledged. A builder that ` +
+                `cleared and did not return looks idle, not broken.`));
+            console.log(chalk.gray('    Recover with:  ') +
+                `afx send <builder> "Read .builder-reorient.md, then run porch next"`);
+        }
+    }
+    {
         const currentPlanPhase = getCurrentPlanPhase(state.plan_phases);
         if (currentPlanPhase) {
             console.log('');