@patronage/software-factory 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { Command } from "commander";
 import { z } from "zod";
+import { readFile } from "node:fs/promises";
 
 //#region src/github-issue-comments.d.ts
 interface GithubIssueCommentApi {
@@ -166,6 +167,195 @@ interface HqIngestDependencies {
   timeoutMs?: number;
   transportTimeoutMs?: number;
 }
+/** The repository whose undelivered evidence a spool holds. */
+interface HqSpoolRepository {
+  owner: string;
+  repo: string;
+}
+/**
+ * What became of one spooled event. `delivered` and `duplicate` both mean HQ
+ * holds it (dedup is by content-addressed eventId), so the entry is removed;
+ * `rejected` and `unreachable` leave it spooled.
+ */
+interface HqSpoolEntryOutcome {
+  detail?: string;
+  eventId: string;
+  kind: string;
+  spool: string;
+  /**
+   * `migrated` belongs to the legacy JSONL journal only: the row was moved
+   * into the current spool without being delivered. The spool pass that runs
+   * after it in the same drain supersedes that line with a real outcome when
+   * it gets to the row; a `migrated` line that survives the run means the row
+   * is still waiting.
+   *
+   * `undeliverable` is the one terminal verdict (#445). Every other status
+   * describes a moment: HQ was unreachable, HQ refused this content today, the
+   * row moved. Retrying is meaningful for all of them. A wrong-origin entry is
+   * different in kind — it is refused here, from the entry's own bytes, with no
+   * request made, and the same bytes produce the same verdict on every future
+   * run. Leaving it spooled asks the operator to retry something that provably
+   * cannot succeed, and the count it inflates is the one doctor goes red on.
+   */
+  status: "delivered" | "duplicate" | "migrated" | "rejected" | "undeliverable" | "unreachable";
+}
+interface HqSpoolFlushInput {
+  clientId: string;
+  clientSecret: string;
+  /** Repository root whose legacy `.factory-memory` spool is also drained. */
+  cwd: string;
+  /** The profile's HQ origin; entries recorded against another are refused. */
+  endpoint: string;
+  /** Operator-named spool directories; replaces the default two locations. */
+  explicitDirectories?: string[];
+  repository: HqSpoolRepository;
+}
+interface HqSpoolFlushSummary {
+  delivered: number;
+  duplicate: number;
+  /**
+   * The drain did not finish: the budget elapsed, or events beyond the
+   * rejected ones are still spooled. Never report an incomplete pass as a
+   * clean drain — a recovery run reads this to know whether to run again.
+   */
+  incomplete: boolean;
+  outcomes: HqSpoolEntryOutcome[];
+  rejected: number;
+  /** Events still in the drained spools when the pass ended. */
+  remaining: number;
+  /** Locations that were read; a missing one is simply absent from the list. */
+  spools: string[];
+  /**
+   * Events dispositioned as permanently undeliverable this pass (#445). They
+   * are gone from `remaining` — that is the point — so this is the only place
+   * the run says they existed.
+   */
+  undeliverable: number;
+  unreachable: number;
+  /** Files retained by a transport failure, counted per file. */
+  unreachableFiles: number;
+}
+interface HqSpoolWorkCount {
+  /**
+   * The earliest moment learned across pending spool files (their own write
+   * time) and legacy journal rows (their own `failedAt`). Absent only when
+   * `pending` is `0`, or when every timestamp source was unreadable within
+   * budget — an estimate for doctor's remediation message (#394), never a
+   * precise audit trail.
+   */
+  oldestQueuedAt?: string;
+  /** Spooled events and replayable journals waiting in the locations below. */
+  pending: number;
+  /** Locations that exist and hold spooled work. */
+  spools: string[];
+  /**
+   * A location existed but could not be listed. The count above saw nothing
+   * there, so a caller deciding whether the drain is worth doing must treat a
+   * non-zero value as "work may be waiting" — never as an empty spool.
+   */
+  unlistable: number;
+}
+/**
+ * Counts spooled work for a repository without draining it or touching a
+ * credential (#414).
+ *
+ * `hq:flush` used to resolve the HQ Access token before it ever looked at the
+ * spool, so a lane with nothing to send still paid a secret-manager round trip
+ * — and still failed, opaquely, in a sandbox that has no keychain access. The
+ * same locations `flushHqSpool` drains are inspected here, read-only: no
+ * directory is created, nothing is secured, and nothing is delivered.
+ */
+declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "cwd" | "explicitDirectories" | "repository">, dependencies?: {
+  budgetMs?: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<HqSpoolWorkCount>;
+/** A spool under an earlier key for this repository, not the current one. */
+interface HqSpoolOrphan {
+  /** The `hq-retry-spool` directory itself, ready to pass to `--dir`. */
+  directory: string;
+  oldestQueuedAt?: string;
+  /** Spooled events and journal rows waiting there. */
+  pending: number;
+  /**
+   * The location exists but could not be listed. As everywhere else in this
+   * inspection, unknown counts as work: a swept location nobody could read is
+   * reported, never quietly dropped as empty.
+   */
+  unlistable: number;
+}
+interface HqSpoolOrphanSweep {
+  /** Only locations holding work; an empty orphan spool is not a finding. */
+  orphans: HqSpoolOrphan[];
+  root: string;
+}
+/**
+ * Reports spooled evidence sitting under an earlier key for *this* repository
+ * (#420).
+ *
+ * The spool is keyed by owner and repo, so a change to the segment encoding
+ * itself — which happened during #390's own development — moves the address
+ * without moving the evidence. Both readers of the spool resolve exactly one
+ * key, so the events under the old one become invisible: the drain reports
+ * success, doctor reports empty, and three real proofs sat unread until an
+ * attended recovery enumerated the tree by hand.
+ *
+ * This sweep only reports. Draining another key's events is a decision this
+ * does not make — the operator gets the location and the count, and
+ * `hq:flush --dir` remains the recovery path.
+ *
+ * **Why candidate keys and not a walk of the root (#446).** The root is shared
+ * by every factory repository on the machine, so enumerating it and calling
+ * everything that is not the current key an orphan describes another
+ * repository's ordinary, current, correct spool exactly as well as it describes
+ * this repository's obsolete one. That made doctor red in one checkout because
+ * a different repository had pending work, and told the operator to drain it —
+ * confidently prescribing the wrong action. Nothing on disk distinguishes the
+ * two cases: an unrecognised key carries no statement about who wrote it.
+ *
+ * So discovery is scoped to the keys *this* repository could plausibly have
+ * produced — the current scheme plus the earlier ones listed in
+ * `hqSpoolCandidateKeys` — and a key outside that set is never this
+ * repository's business. The #420 incident is inside it: the joined
+ * single-segment key is one of the candidates.
+ *
+ * **And a marked walk beside them (#447).** Derivation's other blind spot is a
+ * key whose *encoding* this checkout no longer produces but whose owner and
+ * repo are unchanged — the retired non-injective era being the live example.
+ * That era cannot be derived safely, because a candidate built from it can
+ * equal a different repository's current key, so #446 dropped it rather than
+ * risk the cross-repository claim again.
+ *
+ * `SPOOL_REPOSITORY_MARKER` supplies the proof that derivation could not. Every
+ * enqueue stamps its spool with the repository writing it, so the root can be
+ * walked again: a directory whose marker names *this* repository is this
+ * repository's, whatever key encoding it sits under, and a directory whose
+ * marker names another repository is never reported here. That is the
+ * discriminator #446 correctly said did not exist — it exists now because
+ * something writes it down.
+ *
+ * The two discoveries are complements, not alternatives. The walk sees only
+ * what was stamped; directories written before this shipped have no marker, and
+ * candidate keys still find those. An unmarked directory is still never
+ * reported, because it still carries no statement about who wrote it.
+ *
+ * **What this does NOT close, despite being the marker's obvious use: renames
+ * and owner changes.** A marker records the identity that was current when the
+ * directory was written, so after `patronage/old` becomes `patronage/new` the
+ * stranded directory is stamped `patronage/old` — and matching is equality
+ * against the checkout's *present* identity, which rejects it. Making that work
+ * needs an identifier that survives a rename, which neither the profile nor the
+ * marker carries today; accepting a non-matching marker instead would be
+ * guessing, which is the #446 defect wearing a new hat. #447 stays open for it.
+ *
+ * Also outside the sweep, by construction: evidence under a *different state
+ * root*, if `XDG_STATE_HOME` moves. No walk of this root can reach another one.
+ */
+declare function sweepHqSpoolOrphans(input: {
+  repository: HqSpoolRepository;
+}, dependencies?: {
+  budgetMs?: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<HqSpoolOrphanSweep>;
 //#endregion
 //#region src/demand-waiver.d.ts
 declare const DEFAULT_DEMAND_WAIVER_PATH = ".factory-memory/demand-waivers.json";
@@ -264,6 +454,13 @@ declare const authorizeDemandWaiver: ({
   session: string | undefined;
 }) => AuthorizeDemandWaiverResult;
 //#endregion
+//#region src/blocked-reasons.d.ts
+declare const blockedReasonSchema: z.ZodObject<{
+  code: z.ZodString;
+  detail: z.ZodString;
+}, z.core.$strip>;
+type BlockedReason = z.infer<typeof blockedReasonSchema>;
+//#endregion
 //#region src/checkout-repository.d.ts
 interface CheckoutRepository {
   name: string;
@@ -321,8 +518,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    stale: "stale";
     active: "active";
+    stale: "stale";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1399,8 +1596,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        current: "current";
         stale: "stale";
+        current: "current";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1412,8 +1609,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        current: "current";
         stale: "stale";
+        current: "current";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1430,8 +1627,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
     docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
     prVerify: z.ZodEnum<{
-      passed: "passed";
       stale: "stale";
+      passed: "passed";
       missing: "missing";
     }>;
     trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
@@ -1516,7 +1713,15 @@ interface GitHubPullRequest {
   url: string;
 }
 interface PrReadyProof {
-  schemaVersion: 1;
+  schemaVersion: 2;
+  /**
+   * Why this run blocked, one entry per refusing demand (#391): `code` is the
+   * demand key from the resolver's vocabulary, `detail` the one-sentence
+   * refusal. Same refusals as `blockingReasons`, in the same order — the
+   * analyzable projection of a flat string list, so a wall of blocked proofs
+   * on one PR can be counted by cause. Absent when nothing blocked.
+   */
+  blockedReasons?: BlockedReason[];
   blockingReasons: string[];
   humanBlockingReasons: string[];
   command: "patronage-factory pr:ready";
@@ -1779,8 +1984,8 @@ declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale"
 declare const reviewStatusSchema: z.ZodEnum<{
   blocked: "blocked";
   "not-required": "not-required";
-  current: "current";
   stale: "stale";
+  current: "current";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2369,6 +2574,55 @@ type DemandWaiveAction = (args: DemandWaiveArgs) => DemandWaiver;
 //#region src/commands/pr-merge-check.d.ts
 type PrMergeCheckAction = (args: PrMergeCheckArgs) => PrMergeCheckProof;
 //#endregion
+//#region src/hq-credentials.d.ts
+/**
+ * Why a reference did not resolve. Each value names a different remedy, and
+ * none of them can be inferred from a value-or-nothing result:
+ *
+ * - `resolver-missing` — no secret-manager binary on PATH.
+ * - `resolver-blocked` — a binary exists but this session may not execute it
+ *   (a sandbox denying exec). The command belongs outside the sandbox.
+ * - `resolver-timeout` — the probe expired: a desktop agent waiting on an
+ *   approval nobody can give here.
+ * - `resolver-refused` — the binary ran and produced no value. Its store is
+ *   unreachable from this session (a sandbox with no keychain access) or the
+ *   reference is not readable. These two stay one status on purpose: telling
+ *   them apart would mean reading resolver output.
+ */
+type SecretResolutionFailure = "resolver-blocked" | "resolver-missing" | "resolver-refused" | "resolver-timeout";
+/** A structured resolution outcome. The value travels only when resolved. */
+type SecretResolution = {
+  status: "resolved";
+  value: string;
+} | {
+  status: SecretResolutionFailure;
+};
+/** Resolves a secret reference. Injected so tests stay offline. */
+type SecretReferenceResolver = (reference: string) => SecretResolution;
+//#endregion
+//#region src/hq-flush.d.ts
+/**
+ * Spool locations this run did not drain because they sit under an earlier
+ * key for this repository. Reported, never drained: draining an older key's
+ * events is an operator decision, made with `--dir`.
+ */
+interface HqFlushOrphans {
+  orphans: HqSpoolOrphan[];
+}
+type HqFlushResult = (HqFlushOrphans & {
+  reason: string;
+  /**
+   * Events still spooled when the command gave up. Non-zero means the
+   * skip retained work: the exit status says so, and no caller may read
+   * the skip as "there was nothing to do".
+   */
+  retained: number;
+  status: "skipped";
+}) | (HqFlushOrphans & HqSpoolFlushSummary & {
+  endpoint: string;
+  status: "flushed";
+});
+//#endregion
 //#region src/pr-review.d.ts
 interface PrReviewArgs extends LoadProjectProfileInput {
   base: string;
@@ -2514,6 +2768,15 @@ interface PrPublishDependencies extends PrReadyDependencies {
   runFollowUp?: FollowUpRunner;
   runPrReady?: typeof runPrReady;
   runPrReview?: (args: PrReviewArgs) => Promise<PrReviewProof>;
+  /** Settles asynchronously scheduled sink work before the handoff drain. */
+  awaitPendingIngest?: () => Promise<void>;
+  /**
+   * The handoff drain (#390). Advisory everywhere: publish reports what it
+   * found and never changes its verdict or exit status on the result.
+   */
+  flushHqSpool?: (args: {
+    cwd: string;
+  }) => Promise<HqFlushResult>;
   runPrVerify?: (args: PrVerifyArgs) => Promise<PrVerifyProof>;
   /**
    * Injectable delay for the bounded hosted-run await (#348; tests only —
@@ -3225,8 +3488,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    code: "code";
     review: "review";
+    code: "code";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3304,8 +3567,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    code: "code";
     review: "review";
+    code: "code";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3374,8 +3637,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      code: "code";
       review: "review";
+      code: "code";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -3447,7 +3710,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "code" | "review";
+  purpose: "review" | "code";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;
@@ -3666,13 +3929,39 @@ declare const isBotLogin: (login?: string | undefined) => boolean;
 declare const SHA_MATCH_MIN_LENGTH = 7;
 declare const sameHeadSha: (left: string, right: string) => boolean;
 //#endregion
-//#region src/doctor.d.ts
+//#region src/doctor-hq-checks.d.ts
+/**
+ * Two `doctor` checks that make silent HQ delivery failure loud (#394,
+ * epic #389 wave 2).
+ *
+ * Both consume #414's structured credential resolution rather than inventing
+ * a second classification: a sandboxed session that cannot reach the
+ * keychain is reported as "cannot resolve credentials here", never as
+ * "credentials are wrong" or a silent pass. Both name `psf hq:flush` and
+ * `psf pr:publish` as the commands that need a trusted local session.
+ *
+ * Advisory stays advisory: neither check can block anything but doctor's own
+ * exit status (epic #389 design decision 4). Absent credentials make the
+ * remote check a skip with a printed reason, never a silent pass.
+ */
 type DoctorCheckStatus = "error" | "ok" | "warning";
 interface DoctorCheck {
   message: string;
   name: string;
   status: DoctorCheckStatus;
 }
+interface HqSpoolCheckDependencies {
+  countSpool?: typeof countHqSpoolWork;
+  sweepOrphans?: typeof sweepHqSpoolOrphans;
+}
+interface HqRetroReadbackCheckDependencies {
+  fetch?: typeof fetch;
+  readFile?: typeof readFile;
+  resolve?: SecretReferenceResolver;
+  timeoutMs?: number;
+}
+//#endregion
+//#region src/doctor.d.ts
 interface DoctorReport {
   checks: DoctorCheck[];
   ok: boolean;
@@ -3689,6 +3978,10 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   /** Diff base for the admission preflight; ignored unless `preflight`. */
   base?: string;
   env?: NodeJS.ProcessEnv;
+  /** Test seam for the local HQ spool check (#394); production never sets this. */
+  hqRetroReadbackDependencies?: HqRetroReadbackCheckDependencies;
+  /** Test seam for the remote HQ retro-envelope read-back check (#394). */
+  hqSpoolDependencies?: HqSpoolCheckDependencies;
   /**
    * Append the read-only admission checklist (#292): every requirement this
    * candidate must satisfy before merge, named in one pass. Preflight checks
@@ -3697,7 +3990,7 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   preflight?: boolean;
   userConfig?: LoadUserConfigResult;
 }
-declare function doctorProjectProfile(input?: DoctorProjectProfileInput): DoctorReport;
+declare function doctorProjectProfile(input?: DoctorProjectProfileInput): Promise<DoctorReport>;
 //#endregion
 //#region src/pr-review-gate-trace.d.ts
 interface ReviewGateTraceIdentity {
@@ -4026,6 +4319,10 @@ interface EvaluationInput {
   waveReviewDemand?: Pick<WaveReviewDemand, "review" | "wave">;
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
+  blockedReasons: {
+    code: string;
+    detail: string;
+  }[];
   blockingReasons: string[];
   humanBlockingReasons: string[];
   ledger: {
@@ -4053,14 +4350,14 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "blocked" | "not-required" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "stale" | "current" | "missing";
         docsOnlyDeltaAccepted?: boolean | undefined;
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "blocked" | "not-required" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "stale" | "current" | "missing";
         docsOnlyDeltaAccepted?: boolean | undefined;
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
@@ -4070,7 +4367,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     stackRole: "slice" | "single" | "rollup" | "merge-gate prerequisite";
     verification: {
       command: "patronage-factory pr:verify";
-      prVerify: "passed" | "stale" | "missing";
+      prVerify: "stale" | "passed" | "missing";
       docsOnlyDeltaAccepted?: boolean | undefined;
       docsOnlyVerifiedHeadSha?: string | undefined;
       trivialDeltaAccepted?: boolean | undefined;
@@ -4356,6 +4653,7 @@ type FetchLike = (input: string, init?: {
   headers?: Record<string, string>;
   method?: string;
   redirect?: "error";
+  signal?: AbortSignal;
 }) => Promise<{
   json: () => Promise<unknown>;
   status: number;
@@ -4370,6 +4668,14 @@ interface PublishEpicStructureArgs {
   event: EpicStructureEvent;
   url: string;
   fetchImpl?: FetchLike;
+  /**
+   * Optional caller-owned abort signal. A caller that bounds this call with
+   * its own deadline (e.g. `factory:closeout`'s advisory re-emission, #392)
+   * can abort the in-flight request itself instead of merely abandoning the
+   * `await` — leaving the outbound socket alive past the caller's own
+   * declared timeout.
+   */
+  signal?: AbortSignal;
 }
 interface PublishEpicStructureResult {
   duplicate: boolean;