@cluesmith/codev 3.3.0 → 3.3.2

package/dist/agent-farm/utils/server-utils.d.ts

@@ -19,12 +19,94 @@ export declare function readBody(req: http.IncomingMessage, maxSize?: number): P
  */
 export declare function parseJsonBody(req: http.IncomingMessage, maxSize?: number): Promise<Record<string, unknown>>;
 /**
- * Security: Validate request origin
- * Currently allows all requests - security is handled by the server binding to localhost only.
+ * The expected local key, cached after first read. Issues the key if missing
+ * (Tower is the owner). Returns null and stays fail-closed if the key cannot be
+ * read or created (e.g. an unwritable `~/.agent-farm`).
+ */
+export declare function getExpectedKey(): string | null;
+/**
+ * Reset the cached key. Test-only seam; also lets a future rotation path force
+ * a re-read. Not wired to any runtime rotation in this change.
+ */
+export declare function resetExpectedKeyCache(): void;
+/**
+ * Constant-time key comparison. `timingSafeEqual` throws on unequal-length
+ * buffers, so length is checked first (a length mismatch is an immediate,
+ * non-secret reject).
+ */
+export declare function keysMatch(presented: string, expected: string): boolean;
+/**
+ * Routes intentionally reachable without the key. Kept deliberately narrow:
+ * pre-auth liveness/version probes, the Tower launcher shell, the React
+ * dashboard's static assets (the page loads keyless, then authenticates its
+ * own API/WebSocket calls with the key), the annotator shell + vendor files,
+ * and the cloud OAuth callback. Everything else requires the key.
+ *
+ * The entries here are the paths a *browser navigation* reaches — a top-level
+ * redirect, an iframe load, a `<script>`/`<link>` tag — none of which can
+ * attach the `codev-tower-key` header. Each one therefore carries either no
+ * secret or its own credential; adding a route here means proving that.
+ *
+ * The privileged workspace `file` reader and every `api/` or `ws/` subpath are
+ * explicitly excluded so a static-asset carve-out never exposes a data route.
+ */
+export declare function isPublicRoute(method: string, pathname: string): boolean;
+/**
+ * CORS origin allowlist (advisory Layer 3). Replaces the previous
+ * reflect-any-`https://` behavior. Allowed: loopback origins on any port
+ * (`http://localhost[:port]`, `http://127.0.0.1[:port]`) plus any origins an
+ * operator lists in `CODEV_TOWER_ALLOWED_ORIGINS` (comma-separated, exact
+ * match) for a tunnel/proxy deployment. Secure by default: no wildcard, no
+ * scheme-only reflection. CORS is defense-in-depth; the key check is the
+ * actual control.
+ */
+export declare function isAllowedOrigin(origin: string): boolean;
+/**
+ * Host allowlist (advisory GHSA-xvjp-7748-v88v). A DNS-rebinding guard for the
+ * key-bearing dashboard shell: the key is injected into the (public) shell, so a
+ * browser rebound to Tower's address would carry the attacker's hostname in
+ * `Host` and be rejected before the shell is served. Allowed: loopback hostnames
+ * and the hostnames of any `CODEV_TOWER_ALLOWED_ORIGINS` (the same var the CORS
+ * allowlist uses, so a tunnel/proxy deployment configures both).
+ *
+ * In BRIDGE_MODE the operator has deliberately exposed Tower on the network, so
+ * the allowlist ALSO accepts IP-literal Hosts — a LAN client reaches Tower by IP
+ * (`http://192.168.1.5:4100/`), while DNS rebinding requires a host *name*, which
+ * stays rejected even in bridge mode. Hostname-based LAN access uses the
+ * `CODEV_TOWER_ALLOWED_ORIGINS` escape hatch. The key (mandatory under bridge
+ * mode) remains the primary control and is checked separately for keyed routes;
+ * this relaxation never weakens it.
+ */
+export declare function isAllowedHost(hostHeader: string | undefined): boolean;
+/**
+ * Security: decide whether an HTTP request may proceed.
+ *
+ * Public-allowlisted routes pass keyless; every other route must present a
+ * `codev-tower-key` header that constant-time-matches the expected local key.
+ * Fails closed when the expected key is unavailable.
+ *
  * @param req - HTTP incoming message
- * @returns true (always allowed)
+ * @returns true if the request is authorized
+ */
+export declare function isRequestAllowed(req: http.IncomingMessage): boolean;
+/**
+ * The subprotocol the server echoes back on a terminal WebSocket handshake:
+ * the non-secret marker if the client offered it, else none. NEVER echoes the
+ * `codev-key.<key>` token — echoing it would leak the key into a response
+ * header. Used as the `ws` server's `handleProtocols` (advisory
+ * GHSA-xvjp-7748-v88v). Exported so the echo contract is unit-testable.
+ */
+export declare function selectWsSubprotocol(offered: Set<string>): string | false;
+/**
+ * Security: decide whether a WebSocket upgrade may proceed. Validated at the
+ * handshake (before any PTY attach), independent of the `Origin` header so a
+ * missing Origin can never degrade into an auth bypass. Fails closed when the
+ * expected key is unavailable.
+ *
+ * @param req - HTTP upgrade request
+ * @returns true if the upgrade is authorized
  */
-export declare function isRequestAllowed(_req: http.IncomingMessage): boolean;
+export declare function isWebSocketAllowed(req: http.IncomingMessage): boolean;
 /**
  * Validate a bind host value for server.listen().
  *

package/dist/agent-farm/utils/server-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-utils.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/utils/server-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAEvC;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB1F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyBhH;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,GAAG,OAAO,CAEpE;AACD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiCjD"}
+{"version":3,"file":"server-utils.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/utils/server-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAKvC;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB1F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyBhH;AAsBD;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAS9C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKtE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CA2CvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAWvD;AAwCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CASrE;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,GAAG,OAAO,CAsBnE;AAqBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAExE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,GAAG,OAAO,CAUrE;AACD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiCjD"}

package/dist/agent-farm/utils/server-utils.js

@@ -3,6 +3,9 @@
  * Extracted from tower-server.ts and open-server.ts
  * to eliminate code duplication (Maintenance Run 0004)
  */
+import { timingSafeEqual } from 'node:crypto';
+import { ensureLocalKey } from '@cluesmith/codev-core/auth';
+import { TOWER_KEY_HEADER, LEGACY_WEB_KEY_HEADER, WS_MARKER_PROTOCOL, WS_KEY_PROTOCOL_PREFIX } from '@cluesmith/codev-types';
 /**
  * HTML-escape a string to prevent XSS
  */
@@ -63,14 +66,309 @@ export function parseJsonBody(req, maxSize = 1024 * 1024) {
         req.on('error', reject);
     });
 }
+// ============================================================================
+// Request authentication (advisory GHSA-xvjp-7748-v88v)
+// ============================================================================
+//
+// Tower's local HTTP + WebSocket API reaches privileged local operations, so
+// every request that is not on the narrow public-route allowlist must present
+// the shared local key (`~/.agent-farm/local-key`) in the `codev-tower-key`
+// header. Enforcement is server-side only (server/client isolation, #1189):
+// clients merely transport the key.
+// Wire-contract names (header + WS subprotocols) live in `@cluesmith/codev-types`
+// so the server and every client share one source of truth.
 /**
- * Security: Validate request origin
- * Currently allows all requests - security is handled by the server binding to localhost only.
+ * Cached expected key. `undefined` = not yet loaded; `null` = load failed
+ * (fail closed — reject every authenticated request). Tower owns generation,
+ * so under normal operation the key file exists after boot.
+ */
+let cachedExpectedKey;
+/**
+ * The expected local key, cached after first read. Issues the key if missing
+ * (Tower is the owner). Returns null and stays fail-closed if the key cannot be
+ * read or created (e.g. an unwritable `~/.agent-farm`).
+ */
+export function getExpectedKey() {
+    if (cachedExpectedKey === undefined) {
+        try {
+            cachedExpectedKey = ensureLocalKey() || null;
+        }
+        catch {
+            cachedExpectedKey = null;
+        }
+    }
+    return cachedExpectedKey;
+}
+/**
+ * Reset the cached key. Test-only seam; also lets a future rotation path force
+ * a re-read. Not wired to any runtime rotation in this change.
+ */
+export function resetExpectedKeyCache() {
+    cachedExpectedKey = undefined;
+}
+/**
+ * Constant-time key comparison. `timingSafeEqual` throws on unequal-length
+ * buffers, so length is checked first (a length mismatch is an immediate,
+ * non-secret reject).
+ */
+export function keysMatch(presented, expected) {
+    const a = Buffer.from(presented, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/**
+ * Routes intentionally reachable without the key. Kept deliberately narrow:
+ * pre-auth liveness/version probes, the Tower launcher shell, the React
+ * dashboard's static assets (the page loads keyless, then authenticates its
+ * own API/WebSocket calls with the key), the annotator shell + vendor files,
+ * and the cloud OAuth callback. Everything else requires the key.
+ *
+ * The entries here are the paths a *browser navigation* reaches — a top-level
+ * redirect, an iframe load, a `<script>`/`<link>` tag — none of which can
+ * attach the `codev-tower-key` header. Each one therefore carries either no
+ * secret or its own credential; adding a route here means proving that.
+ *
+ * The privileged workspace `file` reader and every `api/` or `ws/` subpath are
+ * explicitly excluded so a static-asset carve-out never exposes a data route.
+ */
+export function isPublicRoute(method, pathname) {
+    if (method !== 'GET')
+        return false;
+    if (pathname === '/health')
+        return true;
+    if (pathname === '/api/version')
+        return true;
+    if (pathname === '/' || pathname === '/index.html')
+        return true;
+    // Cloud OAuth callback (#1570). cloud.codevos.ai ends registration by
+    // redirecting the browser here, and a cross-site top-level navigation cannot
+    // carry the key header — so the key check can only ever 401 the flow. The
+    // route is self-authenticating instead: the nonce IS the credential. It is
+    // single-use with a 5-minute TTL and can only be minted by an authenticated
+    // POST /api/tunnel/connect, and handleTunnelEndpoint 400s ("Invalid or
+    // expired registration link") without a valid one, so a keyless request
+    // registers nothing. Exact match only — never widen this to an /api/tunnel/
+    // prefix, which would expose the keyed status/disconnect routes.
+    if (pathname === '/api/tunnel/connect/callback')
+        return true;
+    // React SPA served under /workspace/<encoded>/... — static assets only. The
+    // trailing subpath is optional: bare /workspace/<enc> serves the SPA shell,
+    // same as /workspace/<enc>/ (handleWorkspaceRoutes treats them identically).
+    const workspaceMatch = pathname.match(/^\/workspace\/[^/]+(?:\/(.*))?$/);
+    if (workspaceMatch) {
+        const subPath = workspaceMatch[1] || '';
+        // Annotator: its HTML shell and vendor libraries are loaded by iframe
+        // navigation and <script>/<link> tags that cannot carry the key header, so
+        // they are public (no secret; the shell gets the key injected same-origin).
+        // Every data/media sub-route (file, save, api/mtime, api/image, ...) stays
+        // keyed — the shell fetches them with the key.
+        const annotate = subPath.match(/^api\/annotate\/[^/]+(?:\/(.*))?$/);
+        if (annotate) {
+            const annotateSub = annotate[1] || '';
+            return annotateSub === '' || annotateSub.startsWith('vendor/');
+        }
+        if (subPath.startsWith('api/') || subPath === 'api')
+            return false;
+        if (subPath.startsWith('ws/') || subPath === 'ws')
+            return false;
+        if (subPath === 'file')
+            return false;
+        return true;
+    }
+    return false;
+}
+/**
+ * CORS origin allowlist (advisory Layer 3). Replaces the previous
+ * reflect-any-`https://` behavior. Allowed: loopback origins on any port
+ * (`http://localhost[:port]`, `http://127.0.0.1[:port]`) plus any origins an
+ * operator lists in `CODEV_TOWER_ALLOWED_ORIGINS` (comma-separated, exact
+ * match) for a tunnel/proxy deployment. Secure by default: no wildcard, no
+ * scheme-only reflection. CORS is defense-in-depth; the key check is the
+ * actual control.
+ */
+export function isAllowedOrigin(origin) {
+    if (/^http:\/\/localhost(:\d+)?$/.test(origin))
+        return true;
+    if (/^http:\/\/127\.0\.0\.1(:\d+)?$/.test(origin))
+        return true;
+    const configured = process.env.CODEV_TOWER_ALLOWED_ORIGINS;
+    if (configured) {
+        for (const allowed of configured.split(',')) {
+            if (allowed.trim() === origin)
+                return true;
+        }
+    }
+    return false;
+}
+/** Extract the hostname (no port) from a `Host` header value. */
+function hostnameOf(hostHeader) {
+    const h = hostHeader.trim();
+    if (h.startsWith('[')) {
+        // IPv6 literal: [::1] or [::1]:port. The remainder after ] must be empty or
+        // a :port — otherwise the value is malformed and returned whole (matching
+        // nothing on the allowlist) rather than trusting its leading literal.
+        const end = h.indexOf(']');
+        if (end < 0)
+            return h;
+        const rest = h.slice(end + 1);
+        if (rest === '' || /^:\d+$/.test(rest))
+            return h.slice(1, end);
+        return h;
+    }
+    const colon = h.lastIndexOf(':');
+    if (colon >= 0 && /^\d+$/.test(h.slice(colon + 1))) {
+        return h.slice(0, colon);
+    }
+    return h;
+}
+/** True if `hostname` is an IPv4 or IPv6 literal (brackets already stripped). */
+function isIpLiteral(hostname) {
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname))
+        return true; // IPv4
+    return hostname.includes(':'); // IPv6 (a DNS name never contains ':')
+}
+/** True if `hostname` matches a `CODEV_TOWER_ALLOWED_ORIGINS` entry's host. */
+function isConfiguredHost(hostname) {
+    const configured = process.env.CODEV_TOWER_ALLOWED_ORIGINS;
+    if (!configured)
+        return false;
+    for (const origin of configured.split(',')) {
+        try {
+            if (new URL(origin.trim()).hostname.toLowerCase() === hostname)
+                return true;
+        }
+        catch { /* ignore malformed entry */ }
+    }
+    return false;
+}
+/**
+ * Host allowlist (advisory GHSA-xvjp-7748-v88v). A DNS-rebinding guard for the
+ * key-bearing dashboard shell: the key is injected into the (public) shell, so a
+ * browser rebound to Tower's address would carry the attacker's hostname in
+ * `Host` and be rejected before the shell is served. Allowed: loopback hostnames
+ * and the hostnames of any `CODEV_TOWER_ALLOWED_ORIGINS` (the same var the CORS
+ * allowlist uses, so a tunnel/proxy deployment configures both).
+ *
+ * In BRIDGE_MODE the operator has deliberately exposed Tower on the network, so
+ * the allowlist ALSO accepts IP-literal Hosts — a LAN client reaches Tower by IP
+ * (`http://192.168.1.5:4100/`), while DNS rebinding requires a host *name*, which
+ * stays rejected even in bridge mode. Hostname-based LAN access uses the
+ * `CODEV_TOWER_ALLOWED_ORIGINS` escape hatch. The key (mandatory under bridge
+ * mode) remains the primary control and is checked separately for keyed routes;
+ * this relaxation never weakens it.
+ */
+export function isAllowedHost(hostHeader) {
+    if (!hostHeader)
+        return false;
+    const hostname = hostnameOf(hostHeader).toLowerCase();
+    if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1')
+        return true;
+    if (isConfiguredHost(hostname))
+        return true;
+    if (process.env.BRIDGE_MODE === '1' && isIpLiteral(hostname))
+        return true;
+    return false;
+}
+/** Read one header value as a non-empty string, or null. */
+function headerValue(raw) {
+    if (typeof raw === 'string' && raw.length > 0)
+        return raw;
+    if (Array.isArray(raw) && raw.length > 0 && raw[0])
+        return raw[0];
+    return null;
+}
+/**
+ * Read the key a client presented on an HTTP request, or null if absent. Prefers
+ * the current `codev-tower-key` header and falls back to the legacy
+ * `codev-web-key` (dual-accept for one release) so an already-installed client
+ * bundling an older sdk still authenticates while it updates.
+ */
+function presentedHttpKey(req) {
+    return headerValue(req.headers[TOWER_KEY_HEADER]) ?? headerValue(req.headers[LEGACY_WEB_KEY_HEADER]);
+}
+/**
+ * Security: decide whether an HTTP request may proceed.
+ *
+ * Public-allowlisted routes pass keyless; every other route must present a
+ * `codev-tower-key` header that constant-time-matches the expected local key.
+ * Fails closed when the expected key is unavailable.
+ *
  * @param req - HTTP incoming message
- * @returns true (always allowed)
+ * @returns true if the request is authorized
+ */
+export function isRequestAllowed(req) {
+    // Host guard runs first (even for public routes) — the key is injected into the
+    // public dashboard shell, so a rebound Host must not reach it.
+    if (!isAllowedHost(req.headers.host))
+        return false;
+    const method = req.method || 'GET';
+    let pathname = '/';
+    try {
+        pathname = new URL(req.url || '/', 'http://localhost').pathname;
+    }
+    catch {
+        return false;
+    }
+    if (isPublicRoute(method, pathname))
+        return true;
+    const expected = getExpectedKey();
+    if (!expected)
+        return false;
+    const presented = presentedHttpKey(req);
+    if (!presented)
+        return false;
+    return keysMatch(presented, expected);
+}
+/**
+ * Extract the presented key from a WebSocket upgrade's `Sec-WebSocket-Protocol`
+ * offer (the `codev-key.<KEY>` token), or null if absent/malformed.
+ */
+function presentedWsKey(req) {
+    const raw = req.headers['sec-websocket-protocol'];
+    if (!raw)
+        return null;
+    const offered = (Array.isArray(raw) ? raw.join(',') : raw)
+        .split(',')
+        .map((p) => p.trim());
+    for (const proto of offered) {
+        if (proto.startsWith(WS_KEY_PROTOCOL_PREFIX)) {
+            const key = proto.slice(WS_KEY_PROTOCOL_PREFIX.length);
+            return key.length > 0 ? key : null;
+        }
+    }
+    return null;
+}
+/**
+ * The subprotocol the server echoes back on a terminal WebSocket handshake:
+ * the non-secret marker if the client offered it, else none. NEVER echoes the
+ * `codev-key.<key>` token — echoing it would leak the key into a response
+ * header. Used as the `ws` server's `handleProtocols` (advisory
+ * GHSA-xvjp-7748-v88v). Exported so the echo contract is unit-testable.
+ */
+export function selectWsSubprotocol(offered) {
+    return offered.has(WS_MARKER_PROTOCOL) ? WS_MARKER_PROTOCOL : false;
+}
+/**
+ * Security: decide whether a WebSocket upgrade may proceed. Validated at the
+ * handshake (before any PTY attach), independent of the `Origin` header so a
+ * missing Origin can never degrade into an auth bypass. Fails closed when the
+ * expected key is unavailable.
+ *
+ * @param req - HTTP upgrade request
+ * @returns true if the upgrade is authorized
  */
-export function isRequestAllowed(_req) {
-    return true;
+export function isWebSocketAllowed(req) {
+    if (!isAllowedHost(req.headers.host))
+        return false;
+    const expected = getExpectedKey();
+    if (!expected)
+        return false;
+    const presented = presentedWsKey(req);
+    if (!presented)
+        return false;
+    return keysMatch(presented, expected);
 }
 /**
  * Validate a bind host value for server.listen().

package/dist/agent-farm/utils/server-utils.js.map

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

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"}