@staix/agent-hub 0.20.0 → 0.21.0

package/src/hub/sdlc.ts

@@ -3,6 +3,8 @@ import { planConformanceBlockers, type PlanConformance } from "./plan-conformanc
 import { DEFAULT_MAX_NITS, findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CostPlan } from "./cost-governance.ts";
 import { bandsConfig, type BandsConfig } from "./sdlc-metrics.ts";
+import { configPathList, evalGapBlockers, evalGateView, evalRequiredChecks, type EvalGate, type EvalResult } from "./eval-gate.ts";
+import { SECURITY_SOURCES, type SecuritySource } from "./security-baseline.ts";
 import { criteriaReceipt, type CriteriaReceipt, type CriteriaView, type LegacyPhaseReceipt } from "./workflow.ts";
 import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
@@ -36,9 +38,11 @@ export type SdlcMode = "off" | "advise" | "enforce";
 /** #786: `off` never merges, `dry-run` reports the decision and runs nothing, `on` runs the guarded `gh pr merge`. */
 export type AutoMergeMode = "off" | "dry-run" | "on";
 export const AUTO_MERGE_MODES: readonly AutoMergeMode[] = ["off", "dry-run", "on"];
+/** #481 S7: which GitHub alert sources the scan reads, how often, and for which repository (absent: the project repository). */
+export interface SecurityScanConfig { everyH: number; sources: SecuritySource[]; repo?: string }
 /** #786: one repository's own gate: its required checks (before the top-level list) and its own merge mode. */
 export interface RepoMergePolicy { requiredChecks?: string[]; autoMerge?: AutoMergeMode }
-export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; mode: SdlcMode; requiredChecks: string[]; /** #786: absent reads as "off"; written only when the file names it. */ autoMerge?: AutoMergeMode; /** #786: per-repository tables, keyed by lowercase owner/name. */ repos?: Record<string, RepoMergePolicy>; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; /** #481 S7: the scheduled security-scan baseline; absent means none is scheduled. */ securityScan?: SecurityScanConfig; /** #481 S5: the one check a configuration PR needs; no default, the person names it. */ evalCheck?: string; /** #481 S5: patterns that mark a PR as a configuration change; absent reads as the defaults in eval-gate.ts, an empty list turns the gate off. */ configPaths?: string[]; mode: SdlcMode; requiredChecks: string[]; /** #786: absent reads as "off"; written only when the file names it. */ autoMerge?: AutoMergeMode; /** #786: per-repository tables, keyed by lowercase owner/name. */ repos?: Record<string, RepoMergePolicy>; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
 export interface PlanReviewReceipt {
   planner: string;
   planAuthor?: string | null;
@@ -56,6 +60,8 @@ export interface MergeRecord {
   cleanup: "not_started" | "claimed" | "deleted" | "already_gone" | "skipped" | "unknown";
   reason?: "not_merged" | "missing_commit" | "metadata_unknown" | "identity_changed" | "protected_branch" | "default_branch" | "head_changed" | "authority_changed" | "delete_unconfirmed";
   ownerNotice: "not_started" | "claimed" | "sent" | "unknown";
+  /** #481 S7: the merged PR's review and CI figures, read once at merge by the host. Absent when the PR could not be read; fields inside are null when unknown. */
+  cost?: import("./cost-governance.ts").MergeCost;
 }
 export interface SdlcReceipt {
   merge?: MergeRecord;
@@ -152,6 +158,22 @@ const checkList = (value: unknown, what: string): string[] => {
   if (!Array.isArray(value) || value.length > 32 || value.some(c => typeof c !== "string" || !c.trim() || c.length > 120 || /[\r\n\x00-\x1f]/.test(c)) || new Set(value).size !== value.length) throw new Error(`${what}: expected at most 32 unique nonempty names`);
   return [...value] as string[];
 };
+const evalCheckName = (value: unknown): string => {
+  if (typeof value !== "string" || !value.trim() || value.length > 120 || /[\r\n\x00-\x1f]/.test(value)) throw new Error("sdlc.eval_check: expected one nonempty check name");
+  return value;
+};
+const securityScanConfig = (value: unknown): SecurityScanConfig => {
+  const fail = (path: string, why: string): never => { throw new Error(`sdlc.security_scan${path}: ${why}`); };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail("", "expected a table");
+  const raw = value as Record<string, unknown>;
+  for (const key of Object.keys(raw)) if (!["every_h", "sources", "repo"].includes(key)) fail(`.${key}`, "unknown field");
+  const everyH = raw.every_h === undefined ? 24 : raw.every_h;
+  if (typeof everyH !== "number" || !Number.isSafeInteger(everyH) || everyH < 1 || everyH > 720) fail(".every_h", "expected an integer number of hours from 1 to 720");
+  const sources = raw.sources;
+  if (!Array.isArray(sources) || !sources.length || sources.length > SECURITY_SOURCES.length || new Set(sources).size !== sources.length || sources.some(s => !SECURITY_SOURCES.includes(s as SecuritySource))) fail(".sources", `expected a nonempty list of unique names from ${SECURITY_SOURCES.join(", ")}; the scan has no default source`);
+  if (raw.repo !== undefined && !repo(raw.repo)) fail(".repo", "expected owner/repository");
+  return { everyH: everyH as number, sources: [...sources as SecuritySource[]], ...(raw.repo === undefined ? {} : { repo: raw.repo as string }) };
+};
 const autoMergeMode = (value: unknown, what: string): AutoMergeMode => {
   if (!AUTO_MERGE_MODES.includes(value as AutoMergeMode)) throw new Error(`${what}: expected off, dry-run or on`);
   return value as AutoMergeMode;
@@ -178,11 +200,15 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   if (value === undefined) return { mode: "off", requiredChecks: [], stages: [...SDLC_STAGES] };
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc: expected a table");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands", "auto_merge", "repos"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
+  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands", "auto_merge", "repos", "eval_check", "config_paths", "security_scan"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
   const maxNits = raw.max_nits === undefined ? DEFAULT_MAX_NITS : raw.max_nits;
   if (typeof maxNits !== "number" || !Number.isSafeInteger(maxNits) || maxNits < 0 || maxNits > 64) throw new Error("sdlc.max_nits: expected an integer from 0 to 64");
   const bands = bandsConfig(raw.bands), bandConfig = Object.keys(bands).length ? { bands } : {};
-  const findingConfig = { ...(raw.max_nits === undefined ? {} : { maxNits }), ...bandConfig };
+  const evalConfig = {
+    ...(raw.eval_check === undefined ? {} : { evalCheck: evalCheckName(raw.eval_check) }),
+    ...(raw.config_paths === undefined ? {} : { configPaths: configPathList(raw.config_paths, "sdlc.config_paths") }),
+  };
+  const findingConfig = { ...(raw.max_nits === undefined ? {} : { maxNits }), ...bandConfig, ...evalConfig, ...(raw.security_scan === undefined ? {} : { securityScan: securityScanConfig(raw.security_scan) }) };
   const mode = raw.mode ?? "off";
   if (mode !== "off" && mode !== "advise" && mode !== "enforce") throw new Error("sdlc.mode: expected off, advise or enforce");
   // ponytail: the #481 S8 window is a fixed version; delete `workflow`, the phase aliases and their tests once it passes.
@@ -336,12 +362,13 @@ export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
   changed: "spec changed after acceptance: the person re-accepts with ahub sdlc accept <task> --issue <n>",
   unknown: "spec edit time unknown: the issue could not be read",
 };
-export interface SdlcStatus { testIntegrity?: TestIntegrity; planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+export interface SdlcStatus { evalGate?: EvalGate; testIntegrity?: TestIntegrity; planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
 /** The acceptance-criteria checklist (#481 S8, Compliance pass) counts once recorded, and on every task under the retired gsd-lite setting. Off keeps #257's output. */
 export const criteriaRequired = (config: SdlcConfig, receipt: SdlcReceipt | undefined): boolean => config.workflow === "gsd-lite" || (config.mode !== "off" && !!checklistOf(receipt));
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"], integrity?: TestIntegrity): SdlcStatus {
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"], integrity?: TestIntegrity, evalResult?: EvalResult): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
+  const evalGate = evidence ? evalGateView(config, evidence, evalResult) : undefined;
   const items = findingsForHead(sets, findingHead(receipt, evidence, commit));
   const findings = items.length ? findingTally(items) : undefined;
   if (config.mode === "enforce" && findings?.openImportant) blockers.push("open important review findings: " + findings.openImportant);
@@ -355,10 +382,13 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
     if (receipt?.reviewedHead !== evidence.head) blockers.push("current head has not been reviewed");
     if (receipt?.localHead !== evidence.head || receipt.localResult !== "passed") blockers.push("local gate on current head missing or failed");
     if (!config.requiredChecks.length) blockers.push("required check set unknown");
-    for (const name of config.requiredChecks) {
+    // #481 S5: a configuration PR also needs the configured eval check; a code-only PR is unaffected.
+    for (const name of [...new Set([...config.requiredChecks, ...evalRequiredChecks(config, evidence)])]) {
       const matches = evidence.checks.filter(c => c.name === name);
       if (!matches.length || matches.some(c => c.state !== "passed")) blockers.push(`required check ${name}: not successful on current head`);
     }
+    // Gaps in the eval evidence block only in enforce; advise shows them in `evalGate` and the advice notice (never a silent pass, never an advise block).
+    if (config.mode === "enforce") blockers.push(...evalGapBlockers(evalGate));
     if (evidence.review !== "approved") blockers.push("GitHub review approval missing or changes requested");
     if (evidence.pendingReviews !== 0) blockers.push("review requests pending or unknown");
     if (evidence.unresolved !== 0) blockers.push("review threads unresolved or unknown");
@@ -371,7 +401,7 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
   const shown = criteria && (criteriaRequired(config, receipt) || definition && [...definition.entry_gates, ...definition.exit_gates].includes("criteria"));
   // Shown, not counted as a readiness blocker: the spec gate is build entry (#481 S1).
   const spec = config.mode !== "off" && receipt?.issue ? { spec: { issue: receipt.issue, state: specState(receipt, specEdit) } } : {};
-  return { ...spec, ...(config.mode !== "off" && integrity ? { testIntegrity: integrity } : {}), ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+  return { ...spec, ...(evalGate ? { evalGate } : {}), ...(config.mode !== "off" && integrity ? { testIntegrity: integrity } : {}), ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
     actor: !definition ? "person" : shown && criteria.blockers.length ? "reviewer/person" : config.definitions ? definition.actor : baseActor(definition.base),
     // #694: the identity blocker keeps its exact text for gate matching; the next step says how to supply it.
     next: blockers[0] === "issue identity missing" ? "issue identity missing: name one issue (title #N, refs or hub_sdlc_record)" : blockers[0] ?? "person may inspect merge readiness; no automatic merge" };

package/src/hub/security-baseline.ts

@@ -0,0 +1,38 @@
+import type { SdlcGh } from "./sdlc.ts";
+
+/**
+ * #481 S7: the scheduled security-scan baseline. The hub runs no scanner and invents no control: it reads the open-alert counts GitHub already holds for the
+ * repository (Dependabot, secret scanning, code scanning), records one scan row each interval, and the existing control-band path judges the series. A source that
+ * is not enabled, not permitted or unreadable counts as unknown, never as zero alerts, so a repository with no source configured records nothing.
+ */
+export const SECURITY_SOURCES = ["dependabot", "secret_scanning", "code_scanning"] as const;
+export type SecuritySource = typeof SECURITY_SOURCES[number];
+export interface SecurityScan { repo: string; sources: SecuritySource[]; counts: Partial<Record<SecuritySource, number | null>>; total: number | null }
+const PATH: Record<SecuritySource, string> = { dependabot: "dependabot/alerts", secret_scanning: "secret-scanning/alerts", code_scanning: "code-scanning/alerts" };
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const MAX_ALERTS = 1000;
+
+/** Open alerts of one source, exactly (paged to the cap), or null when the source cannot be read completely. Counts only: no alert text, name or location is kept. */
+async function openAlerts(repo: string, source: SecuritySource, run: SdlcGh, deadline: number): Promise<number | null> {
+  let total = 0;
+  for (let page = 1; page <= MAX_ALERTS / 100; page++) {
+    const left = deadline - performance.now();
+    if (left <= 0) return null;
+    const reply = await run(["api", `repos/${repo}/${PATH[source]}?state=open&per_page=100&page=${page}`, "--jq", "length"], Math.min(10_000, left), undefined, 256).catch(() => undefined);
+    if (!reply || reply.code !== 0) return null;
+    const n = Number(reply.stdout.trim());
+    if (!Number.isSafeInteger(n) || n < 0 || n > 100) return null;
+    total += n;
+    if (n < 100) return total;
+  }
+  return null; // more than the cap: unknown, not a clipped number
+}
+
+/** Fixed argv, bounded time and output. The total is known only when every named source was read. */
+export async function readSecurityScan(repo: string, sources: readonly SecuritySource[], run: SdlcGh): Promise<SecurityScan | undefined> {
+  if (!REPO.test(repo) || repo.startsWith("-") || !sources.length || sources.some(source => !SECURITY_SOURCES.includes(source))) return undefined;
+  const deadline = performance.now() + 20_000, counts: SecurityScan["counts"] = {};
+  for (const source of sources) counts[source] = await openAlerts(repo, source, run, deadline);
+  const known = sources.every(source => counts[source] !== null && counts[source] !== undefined);
+  return { repo, sources: [...sources], counts, total: known ? sources.reduce((sum, source) => sum + counts[source]!, 0) : null };
+}

package/src/hub/settings.ts

@@ -1,3 +1,5 @@
+import { OPERATIONAL_NUMBERS } from "./operational-settings.ts";
+import { QUEUE_BACKPRESSURE_LIMITS } from "./queue-backpressure.ts";
 import { operationalRosterSetting, operationalSetting } from "./operational-authority.ts";
 import { ACTION_CLASSES } from "./action-class.ts";
 import { definitionOf, type KindMap, type ProjectAdapterCatalog, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
@@ -57,7 +59,10 @@ export const SETTINGS: readonly SettingDef[] = [
   ...["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "number", min: 1, max: 2_147_483_647 / (key === "interval_s" ? 1000 : 60_000), store: "config", applies: "live", risk: "raises", path: ["task_sweep", key] })),
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "live", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
   { key: "tasks.escalate_after", group: "Routing", label: "Escalate after N consecutive changes_requested", type: "integer", min: 1, max: 10, store: "config", applies: "live", risk: "raises", path: ["tasks", "escalate_after"] },
+  ...OPERATIONAL_NUMBERS.map(({ defaultValue, unit, inventory, ...def }): SettingDef => def),
   { key: "tasks.auto_pull", group: "Switches", label: "Auto-pull the top reserved ready card when a planner slot frees", type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["tasks", "auto_pull"] },
+  { key: "tasks.queue_backpressure.max_queued", group: "Routing", label: "Automatic offers: max queued envelopes (0 disables)", type: "integer", min: 0, max: QUEUE_BACKPRESSURE_LIMITS.max_queued, store: "config", applies: "live", risk: "raises", path: ["tasks", "queue_backpressure", "max_queued"] },
+  { key: "tasks.queue_backpressure.max_oldest_s", group: "Routing", label: "Automatic offers: max oldest queued age in seconds (0 disables)", type: "integer", min: 0, max: QUEUE_BACKPRESSURE_LIMITS.max_oldest_s, store: "config", applies: "live", risk: "raises", path: ["tasks", "queue_backpressure", "max_oldest_s"] },
   { key: "planner", group: "Roles", label: "Planners (task-local selection)", type: "peers", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
@@ -80,7 +85,7 @@ export const SETTINGS: readonly SettingDef[] = [
  * Never editable from settings, whatever the session: these choose what the hub executes or where secrets and task
  * text go. A key equal to an entry, or below it, is refused by name.
  */
-export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "instances", "adapters", "adapter_modules"] as const;
+export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "schedules", "folder_triggers", "corpus", "rooms", "instances", "adapters", "adapter_modules", "local.doc_read", "local.web_fetch"] as const;
 
 /** Derive project-bound rows from the same builtin templates used by lookup, without registering aliases globally. */
 export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): readonly SettingDef[] {

package/src/hub/shipped-packs.ts

@@ -0,0 +1,8 @@
+import example from "../../templates/packs/example.pack.json" with { type: "text" };
+
+/**
+ * The packs the hub ships (#513a), by file name without `.pack.json`. Imported as text so the bundle carries them, as `shipped-roles.ts` carries the role catalog.
+ * Only the format example is here: the writing, analysis and ops packs are #513b, which adds a file to `templates/packs/` and a line here.
+ */
+// TypeScript types a `.json` import as its parsed shape even with `type: "text"`; Bun hands over the file text, which `parsePack` parses and bounds itself.
+export const SHIPPED_PACKS: Readonly<Record<string, string>> = { example: example as unknown as string };

package/src/hub/snapshots.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import { closeSync, constants, copyFileSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, type Stats } from "node:fs";
+import { closeSync, constants, copyFileSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, type Stats } from "node:fs";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -26,6 +26,15 @@ export const budgetNow = (budget: SnapshotBudget): number => budget.now ? budget
 export class SnapshotBudgetExceeded extends Error {
   constructor() { super("snapshot burst budget exhausted; boundary evidence is unknown"); }
 }
+const SNAPSHOT_TIMEOUT_MS = 10_000;
+/**
+ * The wall-clock timeout of one git child. Production (no `budget.now`): the remaining budget, between 1 ms and the 10 s ceiling, so a child is killed at the budget.
+ * ponytail: a host-held clock (`budget.now`, only the host-only snapshotClock seam sets it) holds the deadline, so the child's timeout is the 10 s ceiling, not the remaining budget:
+ * with the clock fixed the remaining budget never shrinks, and 250 ms of real time per child timed a slow git out under load (#554). Production never sets `now`, so its child is still killed
+ * at the budget. A child past the 10 s ceiling still reports ETIMEDOUT and the evidence stays unknown. Upgrade path: a fake spawn seam, if a held clock ever needs to model a slow child.
+ */
+export const childTimeoutMs = (budget?: SnapshotBudget): number =>
+  budget?.now ? SNAPSHOT_TIMEOUT_MS : Math.max(1, Math.min(SNAPSHOT_TIMEOUT_MS, Math.floor(budget ? budget.deadline - budgetNow(budget) : SNAPSHOT_TIMEOUT_MS)));
 const git = (top: string | Repo, args: string[], env: Record<string, string> = {}, budget?: SnapshotBudget, maxBuffer?: number, input?: string | Buffer) => {
   const argv = repoGitArgs(top, args);
   const remaining = budget ? budget.deadline - budgetNow(budget) : SNAPSHOT_TIMEOUT_MS;
@@ -33,12 +42,11 @@ const git = (top: string | Repo, args: string[], env: Record<string, string> = {
   const result = hubGitSync(argv, {
     encoding: "utf8", env: { ...repoGitEnv(top), ...env }, ...(maxBuffer === undefined ? {} : { maxBuffer }),
     ...(input === undefined ? {} : { input }),
-    timeout: Math.max(1, Math.min(SNAPSHOT_TIMEOUT_MS, Math.floor(remaining))),
+    timeout: childTimeoutMs(budget),
   });
   if (budget && (budgetNow(budget) >= budget.deadline || (result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT")) throw new SnapshotBudgetExceeded();
   return result;
 };
-const SNAPSHOT_TIMEOUT_MS = 10_000;
 
 /** A repository and where the project sits in it: `prefix` is "" at the top level, else "sub/dir/". */
 export interface Repo {
@@ -543,6 +551,8 @@ export interface TurnRecord {
   start_tree: string | null;
   end_tree: string | null;
   changed: string[];
+  /** Dirty submodules at the turn's end, whose contents nothing here observes (#798 D2). Absent: not recorded (an older turn, or git could not answer), which is unknown, never none. */
+  unobserved?: string[];
   native: string | null;
 }
 
@@ -606,6 +616,43 @@ export function dirtySubmodules(repo: Repo, budget?: SnapshotBudget): string[] |
   return result.status === 0 ? parseDirtySubmodules(result.stdout) : undefined;
 }
 
+/**
+ * One git-config value as git reads it: an unquoted `#` or `;` starts a comment, a quoted run keeps them, quotes are dropped, and `\"` and `\\` are unescaped inside a quoted
+ * run. ponytail: other escapes (`\t`, octal) are kept as the character after the backslash; use `git config -f .gitmodules --get-regexp path` if a name needs them.
+ */
+function configValue(raw: string): string {
+  let out = "", keep = 0, quoted = false;
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i]!;
+    if (quoted && c === "\\" && i + 1 < raw.length) { out += raw[++i]; keep = out.length; continue; }
+    if (c === '"') { quoted = !quoted; keep = out.length; continue; }
+    if (!quoted && (c === "#" || c === ";")) break;
+    if (!quoted && out.length === 0 && /\s/.test(c)) continue; // leading blanks
+    out += c;
+    if (quoted || !/\s/.test(c)) keep = out.length;       // trailing blanks outside quotes are not part of the value
+  }
+  return out.slice(0, keep);
+}
+
+/**
+ * The submodule paths a project declares, relative to the project (#798 D1), read from `.gitmodules` with no git call. Empty without the file, and for a shadow
+ * repository. A path outside the project's own directory in a larger repository is not the project's. A path git quotes (`"a\tb"`) is taken as written, never
+ * unescaped beyond `\"` and `\\`: see `configValue`.
+ */
+export function submodulePaths(repo: Repo): string[] {
+  if (repo.shadow) return [];
+  let text: string;
+  try { text = readFileSync(join(repo.top, ".gitmodules"), "utf8"); } catch { return []; }
+  const found = new Set<string>();
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*path\s*=(.*)$/.exec(line);
+    let path = match ? configValue(match[1]!) : "";
+    path = path.replace(/\/+$/, "");
+    if (path && !path.startsWith("/") && !path.split("/").includes("..") && path.startsWith(repo.prefix)) found.add(path.slice(repo.prefix.length));
+  }
+  return [...found].sort();
+}
+
 /** Turn records in hub.db: the daemon writes them, `ahub turns` and `ahub undo` read them. */
 export class Turns {
   private readonly db: Database;
@@ -623,6 +670,7 @@ export class Turns {
     this.db.run("CREATE TABLE IF NOT EXISTS touches (task INTEGER NOT NULL, peer TEXT NOT NULL, path TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (task, peer, path))");
     this.db.run("CREATE INDEX IF NOT EXISTS touches_path ON touches (path)"); // the PreToolUse hook looks up one path
     this.db.run("CREATE TABLE IF NOT EXISTS turn_workspaces (turn TEXT PRIMARY KEY, root TEXT NOT NULL, start_tree TEXT, end_tree TEXT, changed TEXT NOT NULL DEFAULT '[]')");
+    this.db.run("CREATE TABLE IF NOT EXISTS turn_unobserved (turn TEXT PRIMARY KEY, paths TEXT NOT NULL)");
     this.db.run("CREATE TABLE IF NOT EXISTS task_snapshots (task INTEGER NOT NULL, proposed_at INTEGER NOT NULL, start_tree TEXT, PRIMARY KEY (task, proposed_at))");
   }
   /** A proposal's original project snapshot; task ids may be reused after reset. Never repair a missing baseline later. */
@@ -665,8 +713,9 @@ export class Turns {
   native(id: string, native: string): void {
     this.db.query("UPDATE turns SET native = ? WHERE id = ? AND native IS NULL").run(native, id);
   }
-  end(id: string, endTree: string | undefined, changed: string[], keep: number): void {
+  end(id: string, endTree: string | undefined, changed: string[], keep: number, unobserved?: string[]): void {
     this.db.transaction(() => {
+      if (unobserved !== undefined) this.db.query("INSERT OR REPLACE INTO turn_unobserved (turn, paths) VALUES (?, ?)").run(id, JSON.stringify(unobserved));
       const scoped = this.workspace(id) !== undefined;
       // Older CLIs do not know workspace receipts. Leave their canonical-checkout snapshot view unknown.
       this.db.query("UPDATE turns SET ended = ?, end_tree = ?, changed = ? WHERE id = ?").run(Date.now(), scoped ? null : endTree ?? null, scoped ? "[]" : JSON.stringify(changed), id);
@@ -675,18 +724,35 @@ export class Turns {
     const peer = (this.db.query("SELECT peer FROM turns WHERE id = ?").get(id) as { peer: string } | null)?.peer;
     if (peer) this.db.query("DELETE FROM turns WHERE peer = ? AND id NOT IN (SELECT id FROM turns WHERE peer = ? ORDER BY started DESC, rowid DESC LIMIT ?)").run(peer, peer, keep);
     this.db.run("DELETE FROM turn_workspaces WHERE turn NOT IN (SELECT id FROM turns)");
+    this.db.run("DELETE FROM turn_unobserved WHERE turn NOT IN (SELECT id FROM turns)");
+  }
+  /** The dirty submodules recorded when the turn ended; undefined when none were recorded (unknown, not "none"). */
+  unobserved(id: string): string[] | undefined {
+    try {
+      const row = this.db.query("SELECT paths FROM turn_unobserved WHERE turn = ?").get(id) as { paths: string } | null;
+      if (!row) return undefined;
+      const paths = JSON.parse(row.paths);
+      return Array.isArray(paths) && paths.every(path => typeof path === "string") ? paths : undefined;
+    } catch (error) {
+      if (/no such table/.test((error as Error).message)) return undefined;
+      throw error;
+    }
+  }
+  private withUnobserved<T extends { id: string }>(record: T): T & { unobserved?: string[] } {
+    const unobserved = this.unobserved(record.id);
+    return unobserved === undefined ? record : { ...record, unobserved };
   }
   list(peer?: string, limit = 20): TurnRecord[] {
     const rows = (peer
       ? this.db.query("SELECT * FROM turns WHERE peer = ? ORDER BY started DESC, rowid DESC LIMIT ?").all(peer, limit)
       : this.db.query("SELECT * FROM turns ORDER BY started DESC, rowid DESC LIMIT ?").all(limit)) as (Omit<TurnRecord, "changed"> & { changed: string })[];
-    return rows.map(row => this.snapshotFields(row)).map((r) => ({ ...r, changed: JSON.parse(r.changed) as string[] }));
+    return rows.map(row => this.snapshotFields(row)).map((r) => this.withUnobserved({ ...r, changed: JSON.parse(r.changed) as string[] }));
   }
   get(id: string): TurnRecord | undefined {
     const r = this.db.query("SELECT * FROM turns WHERE id = ?").get(id) as (Omit<TurnRecord, "changed"> & { changed: string }) | null;
     if (!r) return undefined;
     const record = this.snapshotFields(r);
-    return { ...record, changed: JSON.parse(record.changed) as string[] };
+    return this.withUnobserved({ ...record, changed: JSON.parse(record.changed) as string[] });
   }
   /**
    * Other peers' turns that overlapped this one in time: their changes are in this turn's diff too. `unknown` lists

package/src/hub/source-read.ts

@@ -0,0 +1,160 @@
+import { sanitize } from "./envelope.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { validSourceId } from "./sources.ts";
+import type { SourceMeta } from "./sources.ts";
+
+export const MAX_SOURCE_READ_BYTES = 32 * 1024;
+const CUT_MARKER = " [cut]";
+const REFUSAL = "source read unavailable";
+
+export interface SourceReadRegistry {
+  get(id: string): SourceMeta | undefined;
+  readText(id: string): string | undefined;
+  markPrivate(id: string): SourceMeta | undefined;
+}
+
+export interface SourceReadPolicy {
+  /** Screen the complete stored text. True means clear; false means private or unknown. */
+  screen(text: string, meta: SourceMeta): Promise<boolean>;
+  /** A synchronous, fresh authorization check. */
+  valid(): boolean;
+  /** True only for an authorized on-prem worker inside a PII task. */
+  canReadPrivate(): Promise<boolean>;
+}
+
+export interface SourceReadArgs { id: string; range?: { offset: number; length: number } }
+export type SourceReadResult =
+  | { id: string; kind: SourceMeta["kind"]; private: true }
+  | { id: string; kind: SourceMeta["kind"]; private: true; text: string; next: number }
+  | { id: string; kind: SourceMeta["kind"]; private: false; text: string; next: number };
+
+function refuse(): never { throw new PreEffectToolRefusal(REFUSAL); }
+
+/** Validate the exact tool shape before touching the registry or privacy policy. */
+export function validateSourceRead(value: unknown): SourceReadArgs {
+  if (!value || typeof value !== "object" || Array.isArray(value)) refuse();
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).some(key => key !== "id" && key !== "range") || !validSourceId(input.id)) refuse();
+  if (input.range === undefined) return { id: input.id };
+  if (!input.range || typeof input.range !== "object" || Array.isArray(input.range)) refuse();
+  const range = input.range as Record<string, unknown>;
+  if (Object.keys(range).length !== 2 || Object.keys(range).some(key => key !== "offset" && key !== "length")
+    || !Number.isSafeInteger(range.offset) || (range.offset as number) < 0
+    || !Number.isSafeInteger(range.length) || (range.length as number) < 1
+    || !Number.isSafeInteger((range.offset as number) + (range.length as number))) refuse();
+  return { id: input.id, range: { offset: range.offset as number, length: range.length as number } };
+}
+
+function sameRecord(a: SourceMeta, b: SourceMeta): boolean {
+  return a.id === b.id && a.kind === b.kind && a.origin === b.origin && a.sha256 === b.sha256 && a.bytes === b.bytes
+    && a.added_at === b.added_at && a.private === b.private && JSON.stringify(a.origins) === JSON.stringify(b.origins);
+}
+function sameContent(a: SourceMeta, b: SourceMeta): boolean {
+  return a.id === b.id && a.kind === b.kind && a.sha256 === b.sha256 && a.bytes === b.bytes;
+}
+
+async function privateResult(registry: SourceReadRegistry, id: string, meta: SourceMeta, range: SourceReadArgs["range"], policy: SourceReadPolicy): Promise<SourceReadResult> {
+  const authorized = await policy.canReadPrivate();
+  if (!policy.valid()) refuse();
+  const afterAuth = registry.get(id);
+  if (!afterAuth || !afterAuth.private || !sameRecord(meta, afterAuth)) refuse();
+  if (!authorized) {
+    if (!policy.valid()) refuse();
+    return { id, kind: afterAuth.kind, private: true };
+  }
+  const text = registry.readText(id), finalMeta = registry.get(id);
+  if (text === undefined || !finalMeta?.private || !sameRecord(afterAuth, finalMeta)) refuse();
+  if (!policy.valid()) refuse();
+  return render(id, finalMeta.kind, text, range, true);
+}
+
+/** Screen the whole source before selecting a bounded excerpt; re-read identity and privacy after async policy boundaries. */
+export async function sourceRead(registry: SourceReadRegistry, value: unknown, policy: SourceReadPolicy): Promise<SourceReadResult> {
+  const args = validateSourceRead(value);
+  try {
+    if (!policy.valid()) refuse();
+    let meta = registry.get(args.id);
+    if (!meta) refuse();
+    if (meta.private) {
+      const result = await privateResult(registry, args.id, meta, args.range, policy);
+      if (!policy.valid()) refuse();
+      return result;
+    }
+
+    let fullText = registry.readText(args.id);
+    if (fullText === undefined) refuse();
+    let clear = false;
+    try { clear = await policy.screen(fullText, meta); }
+    catch { clear = false; }
+    if (!policy.valid()) refuse();
+    const afterScreen = registry.get(args.id), afterScreenText = registry.readText(args.id);
+    if (!afterScreen || afterScreenText === undefined || !sameContent(meta, afterScreen) || afterScreenText !== fullText) refuse();
+    if (afterScreen.private) {
+      const result = await privateResult(registry, args.id, afterScreen, args.range, policy);
+      if (!policy.valid()) refuse();
+      return result;
+    }
+    if (!sameRecord(meta, afterScreen)) refuse();
+    meta = afterScreen;
+    if (!clear) {
+      if (!policy.valid()) refuse();
+      meta = registry.markPrivate(args.id) ?? registry.get(args.id);
+      if (!meta?.private) refuse();
+      const result = await privateResult(registry, args.id, meta, args.range, policy);
+      if (!policy.valid()) refuse();
+      return result;
+    }
+
+    if (!policy.valid()) refuse();
+    const current = registry.get(args.id);
+    if (!current || !sameRecord(meta, current) || current.private) refuse();
+    fullText = registry.readText(args.id);
+    if (fullText === undefined || fullText !== afterScreenText) refuse();
+    if (!policy.valid()) refuse();
+    return render(args.id, current.kind, fullText, args.range, false);
+  } catch {
+    refuse();
+  }
+}
+
+/** Walk only the requested, byte-bounded prefix. Sanitizer growth is measured by a bounded binary search over that prefix. */
+function render(id: string, kind: SourceMeta["kind"], fullText: string, range: SourceReadArgs["range"], isPrivate: boolean): SourceReadResult {
+  const offset = range?.offset ?? 0, limit = range?.length ?? Number.MAX_SAFE_INTEGER;
+  const iterator = fullText[Symbol.iterator]();
+  let skipped = 0;
+  while (skipped < offset) {
+    if (iterator.next().done) return isPrivate
+      ? { id, kind, private: true, text: "", next: offset }
+      : { id, kind, private: false, text: "", next: offset };
+    skipped++;
+  }
+
+  const chars: string[] = [];
+  let rawBytes = 0, exhausted = false, stoppedAtByteLimit = false;
+  while (chars.length < limit) {
+    const next = iterator.next();
+    if (next.done) { exhausted = true; break; }
+    const point = next.value;
+    const size = Buffer.byteLength(point, "utf8");
+    if (rawBytes + size > MAX_SOURCE_READ_BYTES) { stoppedAtByteLimit = true; break; }
+    chars.push(point);
+    rawBytes += size;
+  }
+  const hasMoreAfterSelection = stoppedAtByteLimit || (!exhausted && chars.length >= limit && !iterator.next().done);
+  const fits = (count: number): boolean => {
+    const candidate = sanitize(chars.slice(0, count).join(""));
+    const needsMarker = hasMoreAfterSelection || count < chars.length;
+    return Buffer.byteLength(candidate, "utf8") + (needsMarker ? Buffer.byteLength(CUT_MARKER, "utf8") : 0) <= MAX_SOURCE_READ_BYTES;
+  };
+  let low = 0, high = chars.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (fits(middle)) low = middle; else high = middle - 1;
+  }
+  const consumed = low;
+  let text = sanitize(chars.slice(0, consumed).join(""));
+  const hasMore = hasMoreAfterSelection || consumed < chars.length;
+  if (hasMore) text += CUT_MARKER;
+  const next = offset + consumed;
+  return isPrivate ? { id, kind, private: true, text, next } : { id, kind, private: false, text, next };
+}