@patronage/software-factory 1.0.0-alpha.38 → 1.0.0-alpha.39

package/dist/index.d.ts

@@ -22,6 +22,11 @@ declare const githubAppConfigSchema: z.ZodObject<{
   privateKeyPath: z.ZodString;
 }, z.core.$strip>;
 type GithubAppConfig = z.infer<typeof githubAppConfigSchema>;
+declare const hqIngestCredentialReferencesSchema: z.ZodObject<{
+  clientIdRef: z.ZodString;
+  clientSecretRef: z.ZodString;
+}, z.core.$strip>;
+type HqIngestCredentialReferences = z.infer<typeof hqIngestCredentialReferencesSchema>;
 declare const factoryUserConfigSchema: z.ZodObject<{
   githubApp: z.ZodOptional<z.ZodObject<{
     appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
@@ -2226,6 +2231,8 @@ declare const isSupersededHostedVerifyCheck: (check: StatusCheckRollup, cutoffIs
  * `gh` is injectable so a test can hand the real read a fake GitHub.
  */
 declare const fetchGitHubBranchTipSha: (repository: CheckoutRepository, branch: string, cwd: string, gh?: <T>(args: string[], cwd: string) => T) => string;
+/** An asynchronous `gh` JSON read. Injected so a test can hand the reads a fake GitHub. */
+type GhBoundedJsonReader = (args: string[], cwd: string) => Promise<unknown>;
 //#endregion
 //#region src/github-app-client.d.ts
 interface FactoryAppRequest {
@@ -4939,6 +4946,92 @@ interface HqReadinessCheckDependencies {
   timeoutMs?: number;
 }
 //#endregion
+//#region src/hq-last-stored.d.ts
+declare const lastStoredSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  found: z.ZodLiteral<true>;
+  lastFromCaller: z.ZodNullable<z.ZodObject<{
+    anyRepository: z.ZodNullable<z.ZodObject<{
+      receivedAt: z.ZodString;
+    }, z.core.$strip>>;
+    inRepository: z.ZodNullable<z.ZodObject<{
+      receivedAt: z.ZodString;
+    }, z.core.$strip>>;
+    machine: z.ZodString;
+  }, z.core.$strip>>;
+  lastProofEvent: z.ZodNullable<z.ZodObject<{
+    receivedAt: z.ZodString;
+    kind: z.ZodString;
+    observedAt: z.ZodString;
+  }, z.core.$strip>>;
+  lastWebhookEvent: z.ZodNullable<z.ZodObject<{
+    receivedAt: z.ZodString;
+    event: z.ZodString;
+  }, z.core.$strip>>;
+  repository: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  found: z.ZodLiteral<false>;
+  lastFromCaller: z.ZodNullable<z.ZodObject<{
+    anyRepository: z.ZodNullable<z.ZodObject<{
+      receivedAt: z.ZodString;
+    }, z.core.$strip>>;
+    inRepository: z.ZodNullable<z.ZodObject<{
+      receivedAt: z.ZodString;
+    }, z.core.$strip>>;
+    machine: z.ZodString;
+  }, z.core.$strip>>;
+  repository: z.ZodString;
+}, z.core.$strip>], "found">;
+type HqLastStoredAnswer = z.infer<typeof lastStoredSchema>;
+/**
+ * Why HQ gave no answer. `detail` is the operator-facing sentence; it can name
+ * a reference or a status, never a credential value.
+ */
+type HqLastStoredUnknownReason = "no-credentials" | "no-endpoint" | "origin-not-authorized" | "unexpected-response" | "unreachable";
+type HqLastStored = {
+  answer: HqLastStoredAnswer;
+  status: "answered";
+} | {
+  detail: string;
+  reason: HqLastStoredUnknownReason;
+  status: "unknown";
+};
+interface HqLastStoredInput {
+  /** The profile's `hq.endpoint`, HQ's origin. */
+  endpoint: string;
+  env: NodeJS.ProcessEnv;
+  /** The operator's `hqAllowedOrigins`. */
+  hqAllowedOrigins?: readonly string[];
+  hqIngestCredentials?: HqIngestCredentialReferences;
+  repository: {
+    owner: string;
+    repo: string;
+  };
+}
+/** Test seams. Production never sets these. */
+interface HqLastStoredDependencies {
+  fetch?: typeof fetch;
+  resolveSecret?: SecretReferenceResolver;
+  timeoutMs?: number;
+}
+/** Asks HQ when it last stored an event for `repository`. Never throws. */
+declare function fetchHqLastStored(input: HqLastStoredInput, dependencies?: HqLastStoredDependencies): Promise<HqLastStored>;
+//#endregion
+//#region src/doctor-hq-last-stored.d.ts
+/** Test seams. Production never sets these. */
+interface HqLastStoredCheckDependencies {
+  countSpool?: typeof countHqSpoolWork;
+  lastStored?: typeof fetchHqLastStored;
+  now?: () => Date;
+}
+//#endregion
+//#region src/doctor-hq-webhook.d.ts
+/** Test seams. Production never sets these. */
+interface HqWebhookCheckDependencies {
+  gh?: GhBoundedJsonReader;
+  lastStored?: typeof fetchHqLastStored;
+  now?: () => Date;
+}
+//#endregion
 //#region src/doctor-machine-checks.d.ts
 /** Test seams. Production never sets these. */
 interface MachineCheckDependencies {
@@ -4969,10 +5062,14 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   /** Diff base for the admission preflight; ignored unless `preflight`. */
   base?: string;
   env?: NodeJS.ProcessEnv;
+  /** Test seam for the hq-last-stored row (#1342); production never sets this. */
+  hqLastStoredDependencies?: HqLastStoredCheckDependencies;
   /** Test seam for the HQ readiness rows (#1315); production never sets this. */
   hqReadinessDependencies?: HqReadinessCheckDependencies;
   /** Test seam for the local HQ spool check (#394); production never sets this. */
   hqSpoolDependencies?: HqSpoolCheckDependencies;
+  /** Test seam for the hq-webhook row (#1341); production never sets this. */
+  hqWebhookDependencies?: HqWebhookCheckDependencies;
   /** Test seam for the machine readiness rows (#1315); production never sets this. */
   machineDependencies?: MachineCheckDependencies;
   /**

package/dist/index.js

@@ -2,7 +2,7 @@ import { t as __exportAll } from "./chunk-DrSxFLj_.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { Command, InvalidArgumentError } from "commander";
-import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { EventEmitter, once } from "node:events";
 import * as nodeFs from "node:fs";
 import { accessSync, appendFileSync, closeSync, constants, cpSync, existsSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -24,7 +24,7 @@ import { pathToFileURL } from "node:url";
 import { choice, noul, score } from "@typesafe-ai/sdk";
 //#region package.json
 var name = "@patronage/software-factory";
-var version = "1.0.0-alpha.38";
+var version = "1.0.0-alpha.39";
 //#endregion
 //#region src/cli-entry.ts
 /**
@@ -4018,6 +4018,35 @@ const fetchGitHubFileAtRef = (repository, filePath, ref, cwd) => {
 	const response = repositoryFileSchema.parse(runGhJsonAt(["api", `/repos/${repository.owner}/${repository.name}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`], cwd));
 	return Buffer$1.from(response.content, "base64").toString("utf-8");
 };
+/** Ceiling for one bounded `gh` read. Expiry kills gh and rejects. */
+const GITHUB_READ_TIMEOUT_MS = 1e4;
+/**
+* `runGhJsonAt` with a deadline, for a diagnostic that must not hang (#1341).
+* A failure rejects with the `execFile` error: its `stderr` carries gh's
+* `(HTTP nnn)`, and `killed` marks the deadline.
+*/
+const runGhJsonBounded = async (args, cwd) => {
+	const { stdout } = await promisify(execFile)("gh", args, {
+		cwd,
+		encoding: "utf-8",
+		timeout: GITHUB_READ_TIMEOUT_MS
+	});
+	return JSON.parse(stdout);
+};
+const repositoryHooksSchema = z.array(z.object({
+	active: z.boolean(),
+	config: z.object({ url: z.string().optional() }),
+	id: z.number()
+}));
+/**
+* A repository's webhooks (`GET /repos/{owner}/{repo}/hooks`). This needs
+* admin read: a token without it gets 403 or 404, never an empty list. Rejects
+* on every failure; the caller decides what an unreadable list means.
+*/
+const fetchRepositoryHooks = async (repository, cwd, gh = runGhJsonBounded) => repositoryHooksSchema.parse(await gh(["api", `/repos/${repository.owner}/${repository.name}/hooks`], cwd));
+const hookDeliveriesSchema = z.array(z.object({ status_code: z.number() }));
+/** A webhook's last 30 deliveries, newest first. Rejects like `fetchRepositoryHooks`. */
+const fetchHookDeliveries = async (repository, hookId, cwd, gh = runGhJsonBounded) => hookDeliveriesSchema.parse(await gh(["api", `/repos/${repository.owner}/${repository.name}/hooks/${hookId}/deliveries?per_page=30`], cwd));
 /**
 * Fetch and normalize the issue/PR comment thread for `<owner>/<repo>`.
 *
@@ -5296,6 +5325,15 @@ const loadHqAllowedOrigins = async (env, deadline) => {
 * No prefix, wildcard, or host-only match.
 */
 const isHqOriginAuthorized = (allowedOrigins, endpoint) => allowedOrigins.includes(endpoint.origin);
+//#endregion
+//#region src/hq-user-agent.ts
+/**
+* The `User-Agent` every HQ ingest sink request carries (#1343). Without it
+* the sink sends fetch's default, `node`. HQ stores the header in
+* `ingest_events.sender_agent` (#1337), so a look-back can split events by the
+* factory version that sent them.
+*/
+const HQ_SINK_USER_AGENT = `patronage-software-factory/${version} (${process.platform}; node/${process.versions.node})`;
 const DEFAULT_HQ_TRANSPORT_TIMEOUT_MS = 2500;
 const HQ_RETRY_SPOOL_DIRNAME = "hq-retry-spool";
 /**
@@ -6048,7 +6086,10 @@ async function attemptTransport(request, endpoint, clientId, clientSecret, body,
 		clientSecret
 	}, {
 		body,
-		headers: { "content-type": "application/json" },
+		headers: {
+			"content-type": "application/json",
+			"user-agent": HQ_SINK_USER_AGENT
+		},
 		method: "POST",
 		signal: abort.signal
 	}))), transportBudgetMs);
@@ -14923,7 +14964,7 @@ const BASELINE_BLINDSPOT = {
 };
 const NO_CROSS_FAMILY_TOTAL_BLINDSPOT = {
 	id: "no-cross-family-token-total",
-	note: "Token rows are per model family. Claude and GPT use different tokenizers and accounting conventions, so this closeout reports no combined token total. USD is the only cross-family summable unit, and pricing policy stays with the patronage-software-factory-cost-analysis skill."
+	note: "Token rows are per model family. Claude and GPT use different tokenizers and accounting conventions, so this closeout reports no combined token total. USD is the only cross-family summable unit, and pricing policy stays with the patronage-software-factory-lookback skill."
 };
 const assertMetricSources = (metrics) => {
 	for (const metric of metrics) if (!metric.source.detail.trim()) throw new CloseoutValidationError(`metric ${metric.metric} is missing source.detail`);
@@ -14983,7 +15024,7 @@ function buildEpicCloseoutReport(input) {
 * `factory:closeout` reads the lane's native at-rest provider logs by its
 * session join keys and records what they say as closeout metric rows. The
 * rows land in the one local closeout markdown, which is the read path the
-* `patronage-software-factory-cost-analysis` skill uses.
+* `patronage-software-factory-lookback` skill uses.
 *
 * Harvest NEVER throws: a missing or unreadable log degrades to an absent
 * family plus a data gap, so telemetry content can never fail the closeout.
@@ -16150,7 +16191,7 @@ const notProbed = (reason) => ({
 	status: "warning"
 });
 /** A code or an error name. A transport message is never rendered. */
-const networkFailure = (error) => {
+const networkFailure$1 = (error) => {
 	if (!(error instanceof Error)) return "the request failed";
 	if (error.name === "TimeoutError" || error.name === "AbortError") return "it did not answer in time";
 	return `the request failed (${error.cause?.code ?? error.name})`;
@@ -16167,7 +16208,7 @@ const reachableCheck = async (ingest, credentials, dependencies) => {
 		}));
 	} catch (error) {
 		return {
-			message: `HQ at ${ingest.href} is unreachable from this machine: ${networkFailure(error)}. Fix: check this machine's network path to ${ingest.origin}, then rerun doctor.`,
+			message: `HQ at ${ingest.href} is unreachable from this machine: ${networkFailure$1(error)}. Fix: check this machine's network path to ${ingest.origin}, then rerun doctor.`,
 			name: HQ_REACHABLE_CHECK,
 			status: "error"
 		};
@@ -16227,6 +16268,383 @@ async function hqReadinessDoctorChecks(input, dependencies = {}) {
 	];
 }
 //#endregion
+//#region src/hq-last-stored.ts
+/**
+* The HQ client for `GET /api/ingest/last-stored` (#1339): when HQ last stored
+* an event for a repository. Doctor's `hq-webhook` row asks it when GitHub
+* will not show a repository's deliveries (#1341).
+*
+* Whatever HQ cannot answer comes back as an explicit `unknown` with its
+* reason, never a guess. The commonest today is `no-endpoint`: an HQ deployed
+* before #1339 answers the route with 404.
+*
+* The token goes only to an origin the operator listed in `hqAllowedOrigins`
+* or `FACTORY_HQ_ALLOWED_ORIGINS` (ADR 0015, `resolveHqAllowedOrigins`, the
+* rule doctor's `hq-origin` row applies), checked here so no caller can skip
+* it. Credentials resolve the way `hq:flush` resolves them, environment first
+* and then the operator's references, and are held only long enough to send
+* the request.
+*/
+/** HQ's route. `software-factory-hq/src/ingest-config.ts` owns it as `INGEST_LAST_STORED_PATH`. */
+const HQ_LAST_STORED_PATH = "/api/ingest/last-stored";
+/** Ceiling for the request, reply included. Expiry reads as unreachable. */
+const HQ_LAST_STORED_TIMEOUT_MS = 1e4;
+const storedTimeSchema = z.object({ receivedAt: z.string() });
+const lastFromCallerSchema = z.object({
+	anyRepository: storedTimeSchema.nullable(),
+	inRepository: storedTimeSchema.nullable(),
+	machine: z.string()
+}).nullable();
+const lastStoredSchema = z.discriminatedUnion("found", [z.object({
+	found: z.literal(true),
+	lastFromCaller: lastFromCallerSchema,
+	lastProofEvent: storedTimeSchema.extend({
+		kind: z.string(),
+		observedAt: z.string()
+	}).nullable(),
+	lastWebhookEvent: storedTimeSchema.extend({ event: z.string() }).nullable(),
+	repository: z.string()
+}), z.object({
+	found: z.literal(false),
+	lastFromCaller: lastFromCallerSchema,
+	repository: z.string()
+})]);
+const unknown = (reason, detail) => ({
+	detail,
+	reason,
+	status: "unknown"
+});
+/** A code or an error name. A transport message is never rendered. */
+const networkFailure = (error) => {
+	if (!(error instanceof Error)) return "the request failed";
+	if (error.name === "TimeoutError" || error.name === "AbortError") return "it did not answer in time";
+	return `the request failed (${error.cause?.code ?? error.name})`;
+};
+/** Asks HQ when it last stored an event for `repository`. Never throws. */
+async function fetchHqLastStored(input, dependencies = {}) {
+	const origin = validatedHqOrigin(input.endpoint);
+	if (origin === void 0 || !isHqOriginAuthorized(resolveHqAllowedOrigins(input.env, input.hqAllowedOrigins ?? []), origin)) return unknown("origin-not-authorized", `HQ was not asked: ${input.endpoint} is not listed in hqAllowedOrigins in the operator user config or in FACTORY_HQ_ALLOWED_ORIGINS.`);
+	const resolution = resolveHqCredentials({
+		env: input.env,
+		...input.hqIngestCredentials === void 0 ? {} : { references: input.hqIngestCredentials },
+		...dependencies.resolveSecret === void 0 ? {} : { resolve: dependencies.resolveSecret }
+	});
+	if (resolution.status !== "resolved") return unknown("no-credentials", describeHqCredentialFailure(resolution));
+	const url = new URL(HQ_LAST_STORED_PATH, origin.origin);
+	url.searchParams.set("repository", `${input.repository.owner}/${input.repository.repo}`);
+	const request = dependencies.fetch ?? fetch;
+	let response;
+	try {
+		response = await request(url, buildCloudflareAccessRequestInit(resolution.credentials, {
+			method: "GET",
+			signal: AbortSignal.timeout(dependencies.timeoutMs ?? HQ_LAST_STORED_TIMEOUT_MS)
+		}));
+	} catch (error) {
+		return unknown("unreachable", `HQ at ${origin.origin} is unreachable: ${networkFailure(error)}.`);
+	}
+	if (response.status !== 200) {
+		try {
+			await response.body?.cancel();
+		} catch {}
+		return response.status === 404 ? unknown("no-endpoint", `HQ at ${origin.origin} answered 404: it was deployed before GET ${HQ_LAST_STORED_PATH} (#1339).`) : unknown("unexpected-response", `HQ at ${origin.origin} answered ${response.status}.`);
+	}
+	try {
+		return {
+			answer: lastStoredSchema.parse(await response.json()),
+			status: "answered"
+		};
+	} catch {
+		return unknown("unexpected-response", `HQ at ${origin.origin} answered 200 with a reply that is not a last-stored answer.`);
+	}
+}
+//#endregion
+//#region src/doctor-hq-last-stored.ts
+/**
+* The `hq-last-stored` doctor row (#1342): the silent-spool alarm. A machine
+* whose gates stop reaching HQ looks, from HQ, like a machine that stopped
+* working; this row says so from the machine's side.
+*
+* It asks HQ when it last stored an event for this repository (#1339) and
+* prints one line: from this machine, from anyone in this repository, and the
+* last webhook. It warns when this checkout's pr:verify proof is more than an
+* hour newer than HQ's last event from this machine here, or when this
+* repository's spool holds events or cannot be inspected. The spool is read
+* with `countHqSpoolWork`, the reader the `hq-spool` row and `hq:flush` use.
+*
+* Whatever HQ cannot answer (an HQ older than the endpoint, no credentials, a
+* token HQ does not map to a machine) reads "unknown", never a warning. A
+* warning is still never an error: HQ is advisory (ADR 0015, #1228), so
+* doctor's exit code is unchanged. Doctor never flushes; it points at
+* `psf hq:flush`.
+*/
+const HQ_LAST_STORED_CHECK = "hq-last-stored";
+/** How much newer a local proof may be than HQ's copy before the row warns. */
+const BEHIND_TOLERANCE_MS = 36e5;
+const MINUTE_MS = 6e4;
+/** Where pr:verify writes its proof, relative to its cwd (`DEFAULT_PR_VERIFY_PROOF_PATH`). */
+const PR_VERIFY_PROOF_PATH = path.join(".factory-memory", "pr-verify.json");
+/**
+* How long after stamping `endedAt` a pr:verify run writes its own proof, at
+* most, and how far a coarse filesystem clock may put the write before it.
+*/
+const PROOF_WRITE_WINDOW_MS = 6e4;
+const MTIME_GRANULARITY_MS = 2e3;
+/**
+* This checkout's pr:verify proof, and whether a pr:verify run here wrote it.
+* Only such a run handed the proof to the HQ sink, at `endedAt`.
+*
+* `pr:verify --reuse-accepted` writes another run's proof to the same path,
+* byte for byte, with its producer's provenance and time, and sends HQ
+* nothing. It is the one such writer: a proof never travels between heads or
+* stores (ADR 0038). So a proof counts only when it names this profile's
+* path and repository, the identity pr:verify itself uses to call a proof
+* this profile's, and when the file was written as its run ended. Anything
+* else is unattributed: whether HQ is behind is then unknown, never a
+* warning. A missing or unreadable proof is no proof.
+*/
+const readLocalProof = (input) => {
+	const proofPath = path.join(input.cwd, PR_VERIFY_PROOF_PATH);
+	let proof;
+	let writtenAtMs;
+	try {
+		proof = validatePrVerifyProof(JSON.parse(readFileSync(proofPath, "utf-8")));
+		writtenAtMs = statSync(proofPath).mtimeMs;
+	} catch {
+		return { status: "none" };
+	}
+	const { name, owner } = input.profile.repository;
+	const writeLag = writtenAtMs - Date.parse(proof.endedAt);
+	return proof.profilePath === input.profilePath && proof.repository === `${owner}/${name}` && writeLag >= -MTIME_GRANULARITY_MS && writeLag <= PROOF_WRITE_WINDOW_MS ? {
+		endedAt: proof.endedAt,
+		status: "local"
+	} : { status: "unattributed" };
+};
+const ago = (at, now) => {
+	const minutes = Math.floor((now.getTime() - Date.parse(at)) / MINUTE_MS);
+	if (!Number.isFinite(minutes)) return `at ${at}`;
+	if (minutes < 60) return `${Math.max(minutes, 0)} min ago`;
+	const hours = Math.floor(minutes / 60);
+	return hours < 24 ? `${hours} h ago` : `${Math.floor(hours / 24)} d ago`;
+};
+const summary$1 = (answer, now) => {
+	const caller = answer.lastFromCaller;
+	let machine = "unknown sender";
+	if (caller?.inRepository) machine = ago(caller.inRepository.receivedAt, now);
+	else if (caller?.anyRepository) machine = `never here (elsewhere ${ago(caller.anyRepository.receivedAt, now)})`;
+	else if (caller) machine = "never";
+	const proof = answer.found ? answer.lastProofEvent : null;
+	const webhook = answer.found ? answer.lastWebhookEvent : null;
+	return [
+		`HQ last stored: from this machine ${machine}`,
+		`from this repository ${proof ? ago(proof.receivedAt, now) : "never"}`,
+		`webhook ${webhook ? ago(webhook.receivedAt, now) : "never"}.`
+	].join(" · ");
+};
+/** What this checkout's proof says about HQ's copy, when it says anything. */
+const comparison = (answer, local) => {
+	const caller = answer.lastFromCaller;
+	if (caller === null || local.status === "none") return;
+	if (local.status === "unattributed") return {
+		behind: false,
+		note: "This checkout's pr:verify proof was not written here by pr:verify for this repository (a reused proof keeps its producer's time), so whether HQ is behind this machine is unknown."
+	};
+	if (caller.inRepository === null) return {
+		behind: true,
+		note: `This checkout's pr:verify proof ended at ${local.endedAt}, and HQ has stored nothing from this machine in this repository.`
+	};
+	return Date.parse(local.endedAt) - Date.parse(caller.inRepository.receivedAt) > BEHIND_TOLERANCE_MS ? {
+		behind: true,
+		note: `This checkout's pr:verify proof ended at ${local.endedAt}, more than 1 h after HQ last stored an event from this machine here.`
+	} : void 0;
+};
+/**
+* The spool as the reason HQ is behind; the hq-spool row has the detail. The
+* spool is called empty only when it was fully inspected.
+*/
+const spoolNotes = (spool, behind) => {
+	const notes = [...spool.pending > 0 ? [`HQ is behind by the ${spool.pending} event(s) the hq-spool row reports; \`psf hq:flush\` sends them.`] : [], ...spool.unlistable > 0 ? [`${spool.unlistable} spool location(s) could not be inspected, so the events waiting there are unknown; the hq-spool row names them.`] : []];
+	return notes.length === 0 && behind ? ["Nothing is spooled here, so `psf hq:flush` has nothing to send."] : notes;
+};
+const unknownLine = (lastStored) => lastStored.reason === "no-credentials" ? `HQ last stored: unknown (no HQ credentials). ${lastStored.detail}` : `HQ last stored: unknown. ${lastStored.detail}`;
+async function hqLastStoredDoctorCheck(input, dependencies = {}) {
+	const { hq, repository } = input.profile;
+	if (!hq?.enabled) return {
+		message: "Not an HQ repository: the profile does not enable HQ ingest, so HQ is not asked.",
+		name: HQ_LAST_STORED_CHECK,
+		status: "ok"
+	};
+	const slug = {
+		owner: repository.owner,
+		repo: repository.name
+	};
+	const [lastStored, spool] = await Promise.all([(dependencies.lastStored ?? fetchHqLastStored)({
+		endpoint: hq.endpoint,
+		env: input.env,
+		hqAllowedOrigins: input.userConfig?.hqAllowedOrigins,
+		hqIngestCredentials: input.userConfig?.hqIngestCredentials,
+		repository: slug
+	}), (dependencies.countSpool ?? countHqSpoolWork)({ repository: slug }, { env: input.env })]);
+	const now = dependencies.now?.() ?? /* @__PURE__ */ new Date();
+	const compared = lastStored.status === "answered" ? comparison(lastStored.answer, readLocalProof(input)) : void 0;
+	const behind = compared?.behind ?? false;
+	const unidentified = lastStored.status === "answered" && lastStored.answer.lastFromCaller === null ? "HQ does not know which machine this token belongs to, so this machine's proofs are not compared." : void 0;
+	return {
+		message: [
+			lastStored.status === "answered" ? summary$1(lastStored.answer, now) : unknownLine(lastStored),
+			unidentified,
+			compared?.note,
+			...spoolNotes(spool, behind)
+		].filter((note) => note !== void 0).join(" "),
+		name: HQ_LAST_STORED_CHECK,
+		status: behind || spool.pending > 0 || spool.unlistable > 0 ? "warning" : "ok"
+	};
+}
+//#endregion
+//#region src/doctor-hq-webhook.ts
+/**
+* The `hq-webhook` doctor row (#1341): whether GitHub's webhook deliveries
+* from this repository reach HQ. paitronage and firedup answered 401 from
+* 2026-07-17 on and nothing said so; this row warns on the first one.
+*
+* It reads the repository hook whose URL is the profile's HQ origin plus
+* `/webhooks/github`, then that hook's last 30 deliveries, with the `gh`
+* credential doctor already uses. It warns on a 401 (the secret does not match
+* HQ's), any other 4xx, a 5xx, a delivery that got no response, or no hook at
+* all. HQ answers an out-of-scope delivery 202 (#1338), so any 4xx is a broken
+* delivery: HQ rejected it and stored nothing.
+*
+* Reading hooks needs admin on the repository, which many operators do not
+* have. When GitHub will not show the deliveries, the row warns and falls back
+* to HQ's own record, `GET /api/ingest/last-stored`, so a non-admin still gets
+* an answer, or an explicit "unknown" with its reason.
+*
+* A warning, never an error: HQ is advisory (ADR 0015, #1228), so HQ being
+* deaf never changes doctor's exit code. The row only reads; it never creates,
+* edits or redelivers a hook.
+*/
+const HQ_WEBHOOK_CHECK = "hq-webhook";
+/** HQ's webhook route. `software-factory-hq/src/webhooks/config.ts` owns it as `GITHUB_WEBHOOK_PATH`. */
+const HQ_WEBHOOK_PATH = "/webhooks/github";
+const HTTP_STATUS_PATTERN$1 = /\bHTTP (?<status>\d{3})\b/u;
+const DAY_MS = 864e5;
+const sameUrl = (candidate, expected) => {
+	try {
+		return candidate !== void 0 && new URL(candidate).href === expected;
+	} catch {
+		return false;
+	}
+};
+/**
+* Why a GitHub read failed, from gh's own `(HTTP nnn)` and the deadline. The
+* error text is read here and dropped.
+*/
+const githubFailure = (error, slug) => {
+	const failure = error;
+	if (failure.killed === true) return "GitHub did not answer in time";
+	const text = typeof failure.stderr === "string" ? failure.stderr : failure.message ?? "";
+	const status = Number(HTTP_STATUS_PATTERN$1.exec(text)?.groups?.status ?? 0);
+	if (status === 403 || status === 404) return `GitHub answered ${status}, so this gh token has no admin read on ${slug}`;
+	if (status !== 0) return `GitHub answered ${status}`;
+	return "gh could not read GitHub; check `gh auth status`";
+};
+const daysAgo = (receivedAt, now) => {
+	const days = Math.floor((now.getTime() - Date.parse(receivedAt)) / DAY_MS);
+	if (!Number.isFinite(days)) return `at ${receivedAt}`;
+	return `${days} day${days === 1 ? "" : "s"} ago (${receivedAt})`;
+};
+const describeLastStored = (lastStored, now) => {
+	if (lastStored.status === "unknown") return `HQ's last stored webhook is unknown: ${lastStored.detail}`;
+	const { answer } = lastStored;
+	if (!answer.found) return "HQ has never stored an event from this repository.";
+	if (answer.lastWebhookEvent === null) return "HQ has stored events from this repository, but never a webhook delivery.";
+	return `HQ last stored a webhook from this repository ${daysAgo(answer.lastWebhookEvent.receivedAt, now)}, a ${answer.lastWebhookEvent.event} event.`;
+};
+/**
+* GitHub will not show the deliveries, so the row warns, says why, and reports
+* what HQ last stored instead.
+*/
+const unreadableCheck = async (input, hq, error, dependencies) => {
+	const { repository } = input.profile;
+	const slug = `${repository.owner}/${repository.name}`;
+	const lastStored = await (dependencies.lastStored ?? fetchHqLastStored)({
+		endpoint: hq.endpoint,
+		env: input.env,
+		hqAllowedOrigins: input.userConfig?.hqAllowedOrigins,
+		hqIngestCredentials: input.userConfig?.hqIngestCredentials,
+		repository: {
+			owner: repository.owner,
+			repo: repository.name
+		}
+	});
+	return {
+		message: `Can't read ${slug}'s webhook deliveries: ${githubFailure(error, slug)}. ${describeLastStored(lastStored, dependencies.now?.() ?? /* @__PURE__ */ new Date())}`,
+		name: HQ_WEBHOOK_CHECK,
+		status: "warning"
+	};
+};
+/** `n × code` per status, in the order given. Code 0 is no response. */
+const describeCounts = (counted) => counted.map(([code, n]) => `${n} × ${code === 0 ? "no response" : code}`).join(", ");
+const deliveriesCheck = (hookId, hookUrl, deliveries) => {
+	if (deliveries.length === 0) return {
+		message: `Hook ${hookId} delivers to ${hookUrl}; GitHub lists no recent deliveries for it.`,
+		name: HQ_WEBHOOK_CHECK,
+		status: "ok"
+	};
+	const tally = /* @__PURE__ */ new Map();
+	for (const { status_code: code } of deliveries) {
+		const key = code < 100 ? 0 : code;
+		tally.set(key, (tally.get(key) ?? 0) + 1);
+	}
+	const counted = [...tally].toSorted(([left], [right]) => left - right);
+	const unauthorized = tally.get(401) ?? 0;
+	const rejected = counted.filter(([code]) => code >= 400 && code < 500 && code !== 401);
+	const rejectedCount = rejected.reduce((total, [, n]) => total + n, 0);
+	const noResponse = tally.get(0) ?? 0;
+	const serverErrors = deliveries.filter(({ status_code: code }) => code >= 500).length;
+	const warnings = [
+		...unauthorized > 0 ? [`${unauthorized} got 401: the webhook secret does not match HQ's; see #1310.`] : [],
+		...rejectedCount > 0 ? [`${rejectedCount} got a 4xx other than 401 (${describeCounts(rejected)}): HQ rejected each delivery and stored nothing.`] : [],
+		...serverErrors > 0 ? [`${serverErrors} got a 5xx from HQ.`] : [],
+		...noResponse > 0 ? [`${noResponse} got no response from HQ (timed out or unreachable).`] : []
+	];
+	return {
+		message: [`Hook ${hookId} delivers to ${hookUrl}; its last ${deliveries.length} deliveries: ${describeCounts(counted)}.`, ...warnings].join(" "),
+		name: HQ_WEBHOOK_CHECK,
+		status: warnings.length > 0 ? "warning" : "ok"
+	};
+};
+async function hqWebhookDoctorCheck(input, dependencies = {}) {
+	const { hq, repository } = input.profile;
+	if (!hq?.enabled) return {
+		message: "The profile does not enable HQ ingest, so no webhook delivery is checked.",
+		name: HQ_WEBHOOK_CHECK,
+		status: "ok"
+	};
+	const hookUrl = new URL(HQ_WEBHOOK_PATH, hq.endpoint).href;
+	let hooks;
+	try {
+		hooks = await fetchRepositoryHooks(repository, input.cwd, dependencies.gh);
+	} catch (error) {
+		return unreadableCheck(input, hq, error, dependencies);
+	}
+	const hook = hooks.find((candidate) => sameUrl(candidate.config.url, hookUrl));
+	if (hook === void 0) return {
+		message: `No webhook on ${repository.owner}/${repository.name} delivers to ${hookUrl}, so HQ hears no GitHub event from this repository. Fix: a repository admin adds one with payload URL ${hookUrl}, content type json, the events check_run, issues, pull_request and push, and the secret HQ holds.`,
+		name: HQ_WEBHOOK_CHECK,
+		status: "warning"
+	};
+	if (!hook.active) return {
+		message: `Hook ${hook.id} to ${hookUrl} is disabled in GitHub, so no new event from ${repository.owner}/${repository.name} reaches HQ. Fix: a repository admin re-enables it in Settings → Webhooks.`,
+		name: HQ_WEBHOOK_CHECK,
+		status: "warning"
+	};
+	try {
+		return deliveriesCheck(hook.id, hookUrl, await fetchHookDeliveries(repository, hook.id, input.cwd, dependencies.gh));
+	} catch (error) {
+		return unreadableCheck(input, hq, error, dependencies);
+	}
+}
+//#endregion
 //#region src/doctor-machine-checks.ts
 /**
 * Machine readiness rows for `doctor` (#1315): facts about this machine, not
@@ -16430,6 +16848,19 @@ async function doctorProjectProfile(input = {}) {
 		}),
 		...hqReadinessChecks,
 		hqSpoolCheck,
+		await hqWebhookDoctorCheck({
+			cwd,
+			env,
+			profile,
+			userConfig: userConfig.loaded?.config
+		}, input.hqWebhookDependencies),
+		await hqLastStoredDoctorCheck({
+			cwd,
+			env,
+			profile,
+			profilePath: path,
+			userConfig: userConfig.loaded?.config
+		}, input.hqLastStoredDependencies),
 		...machineDoctorChecks({
 			env,
 			profile,
@@ -16888,12 +17319,18 @@ const publishEpicStructure = async (args) => {
 	const doFetch = args.fetchImpl ?? globalThis.fetch;
 	const requestInit = args.accessServiceToken ? buildCloudflareAccessRequestInit(args.accessServiceToken, {
 		body: JSON.stringify(args.event),
-		headers: { "content-type": "application/json" },
+		headers: {
+			"content-type": "application/json",
+			"user-agent": HQ_SINK_USER_AGENT
+		},
 		method: "POST",
 		...args.signal ? { signal: args.signal } : {}
 	}) : {
 		body: JSON.stringify(args.event),
-		headers: { "content-type": "application/json" },
+		headers: {
+			"content-type": "application/json",
+			"user-agent": HQ_SINK_USER_AGENT
+		},
 		method: "POST",
 		...args.signal ? { signal: args.signal } : {}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "1.0.0-alpha.38",
+  "version": "1.0.0-alpha.39",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {
@@ -42,7 +42,7 @@
     "picomatch": "^4.0.5",
     "yaml": "^2.9.0",
     "zod": "4.4.3",
-    "@patronage/factory-ci": "1.0.0-alpha.38"
+    "@patronage/factory-ci": "1.0.0-alpha.39"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.76.0",