@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/eval-gate.ts

@@ -0,0 +1,131 @@
+import type { PrEvidence, SdlcConfig, SdlcGh } from "./sdlc.ts";
+import { completePlanInventory } from "./plan-conformance.ts";
+
+/**
+ * #481 S5: the gate MECHANISM for agent-configuration PRs. A PR whose changed paths match `config_paths` needs the one check named by `eval_check`.
+ * The hub chooses, creates and defaults to no suite: `eval_check` has no default, and the person names it (suite choice pending the person).
+ */
+export const DEFAULT_CONFIG_PATHS: readonly string[] = [
+  "AGENTS.md", "docs/agent-notes/**", "templates/**", ".agenthub/roles/**", ".agenthub/routing.toml", "routing.toml", "src/hub/hub-tools.ts",
+];
+const MAX_PATTERNS = 32;
+
+/** Repository-relative patterns: literal names, `*` and `?` inside one segment, and a whole-segment `**`. Anything else is refused at load. */
+export function configPathList(value: unknown, what: string): string[] {
+  const bad = () => new Error(`${what}: expected at most ${MAX_PATTERNS} unique repository-relative patterns (literal names, * and ? inside a segment, whole-segment **)`);
+  if (!Array.isArray(value) || value.length > MAX_PATTERNS || new Set(value).size !== value.length) throw bad();
+  for (const pattern of value) {
+    if (typeof pattern !== "string" || !pattern || pattern.length > 200 || /[\p{Cc}\p{Cf}\\]/u.test(pattern) || pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern)) throw bad();
+    const parts = pattern.split("/");
+    if (parts.some(part => part === "" || part === "." || part === ".." || (part.includes("**") && part !== "**"))) throw bad();
+  }
+  return [...value] as string[];
+}
+
+const segmentRegex = (part: string) => new RegExp(`^${part.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")}$`);
+/** Pure, lexical, no filesystem. `dir/**` matches everything under `dir`, never `dir` itself. */
+export function matchConfigPath(pattern: string, path: string): boolean {
+  const p = pattern.split("/"), s = path.split("/");
+  const walk = (i: number, j: number): boolean => {
+    if (i === p.length) return j === s.length;
+    if (p[i] === "**") { for (let k = j + 1; k <= s.length; k++) if (walk(i + 1, k)) return true; return false; }
+    return j < s.length && segmentRegex(p[i]!).test(s[j]!) && walk(i + 1, j + 1);
+  };
+  return walk(0, 0);
+}
+
+export type EvalApplies = "config" | "code" | "unknown";
+export const configPathsOf = (config: Pick<SdlcConfig, "configPaths">): readonly string[] => config.configPaths ?? DEFAULT_CONFIG_PATHS;
+
+/** `unknown` when the file inventory is not complete (never a clean code-only claim); `code` for a PR touching no configured path, an empty `config_paths` included. */
+export function evalApplies(config: Pick<SdlcConfig, "configPaths">, evidence: PrEvidence | undefined): { applies: EvalApplies; matched: string[] } {
+  const paths = configPathsOf(config);
+  if (!paths.length) return { applies: "code", matched: [] };
+  const inventory = completePlanInventory(evidence);
+  if (inventory === undefined) return { applies: "unknown", matched: [] };
+  const matched = inventory.filter(path => paths.some(pattern => matchConfigPath(pattern, path))).sort();
+  return { applies: matched.length ? "config" : "code", matched };
+}
+
+/** The extra required check for this reading of the PR: the configured eval check, only for a configuration PR. */
+export function evalRequiredChecks(config: Pick<SdlcConfig, "configPaths" | "evalCheck" | "mode">, evidence: PrEvidence | undefined): string[] {
+  if (config.mode === "off" || !config.evalCheck) return [];
+  return evalApplies(config, evidence).applies === "config" ? [config.evalCheck] : [];
+}
+
+/** What the eval check run reported, never its text: two bounded values read from a fixed marker (`eval_pass_rate=<0..1>`, `eval_suite=<version>`). */
+export interface EvalResult { check: string; head: string; passRate?: number; suite?: string; read: boolean }
+export interface EvalGate {
+  applies: "config" | "unknown";
+  /** How many changed files matched `config_paths`; names stay out of the view (counts and identities only). */
+  files: number;
+  check?: string;
+  state: "not_configured" | "coverage_unknown" | "passed" | "failed" | "pending" | "missing" | "unknown";
+  passRate?: number;
+  suite?: string;
+  /** Evidence gaps that were required of a configured gate: shown in every enabled mode, blockers only in enforce. */
+  gaps: string[];
+  /** Shown, never a blocker in any mode: the gate has no suite behind it yet (suite choice pending the person). */
+  notes?: string[];
+}
+export const EVAL_NOT_CONFIGURED = "eval check not configured: the person names one with eval_check in sdlc.toml (suite choice pending the person)";
+export const EVAL_COVERAGE_UNKNOWN = "eval gate: PR file coverage incomplete or unknown";
+export const evalReportedGap = (check: string) => `eval gate: pass rate or suite version not reported by ${check}`;
+const reported = evalReportedGap;
+
+/** Undefined for off mode and for a code-only PR: those outputs stay byte-identical. */
+export function evalGateView(config: Pick<SdlcConfig, "configPaths" | "evalCheck" | "mode">, evidence: PrEvidence | undefined, result?: EvalResult): EvalGate | undefined {
+  if (config.mode === "off") return undefined;
+  const { applies, matched } = evalApplies(config, evidence);
+  if (applies === "code") return undefined;
+  const check = config.evalCheck;
+  // With no eval check named there is nothing to require: say so, and never block. Enforce users gain no new refusal until the person names a suite.
+  if (!check) return applies === "unknown" ? undefined : { applies, files: matched.length, state: "not_configured", gaps: [], notes: [EVAL_NOT_CONFIGURED] };
+  if (applies === "unknown") return { applies, files: 0, state: "coverage_unknown", check, gaps: [EVAL_COVERAGE_UNKNOWN] };
+  const found = evidence!.checks.filter(c => c.name === check);
+  const state = !found.length ? "missing" : found.some(c => c.state === "failed") ? "failed" : found.some(c => c.state === "pending") ? "pending" : found.every(c => c.state === "passed") ? "passed" : "unknown";
+  const view: EvalGate = { applies, files: matched.length, check, state, gaps: [] };
+  // The record is read only for a passed check at this head; a result read for another head or check is never shown.
+  if (result && result.read && result.check === check && result.head === evidence!.head) {
+    if (result.passRate !== undefined) view.passRate = result.passRate;
+    if (result.suite !== undefined) view.suite = result.suite;
+  }
+  if (state === "passed" && result && (view.passRate === undefined || view.suite === undefined)) view.gaps.push(reported(check));
+  return view;
+}
+/** Evidence gaps that block in enforce. The state of the check itself is an ordinary required-check blocker. */
+export const evalGapBlockers = (view: EvalGate | undefined): string[] => view?.gaps ?? [];
+/** What advise shows beside the gaps: gaps and notes, each once. */
+export const evalAdvice = (view: EvalGate | undefined): string[] => [...(view?.gaps ?? []), ...(view?.notes ?? [])];
+
+const MARK_RATE = /(?:^|\s)eval_pass_rate=(0(?:\.[0-9]{1,6})?|1(?:\.0{1,6})?)(?=\s|$)/;
+const MARK_SUITE = /(?:^|\s)eval_suite=([A-Za-z0-9][A-Za-z0-9._-]{0,39})(?=\s|$)/;
+const SHA = /^[a-f0-9]{40}$/;
+/** Pure: the two markers, or nothing. The rest of the text is never kept. */
+export function parseEvalMarkers(text: string): { passRate?: number; suite?: string } {
+  const rate = MARK_RATE.exec(text.slice(0, 2000))?.[1], suite = MARK_SUITE.exec(text.slice(0, 2000))?.[1];
+  return { ...(rate === undefined ? {} : { passRate: Number(rate) }), ...(suite === undefined ? {} : { suite }) };
+}
+
+/** Read-only, fixed argv, bounded output and time. One completed check run of that exact name at that exact head, else `read: false`. */
+export async function readEvalResult(repository: string, head: string, check: string, run: SdlcGh): Promise<EvalResult> {
+  const none: EvalResult = { check, head, read: false };
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || repository.startsWith("-") || !SHA.test(head) || !check || check.length > 120 || /[\x00-\x1f]/.test(check)) return none;
+  try {
+    const reply = await run(["api", `repos/${repository}/commits/${head}/check-runs?check_name=${encodeURIComponent(check)}&per_page=10`, "--jq",
+      '{total_count,check_runs:[.check_runs[]|{name,status,conclusion,head_sha,text:(((.output.title // "")+" "+(.output.summary // ""))|.[0:1000])}]}'], 10_000, undefined, 32 * 1024);
+    if (reply.code !== 0) return none;
+    const parsed = JSON.parse(reply.stdout), runs = parsed?.check_runs;
+    if (!Array.isArray(runs) || runs.length > 10 || parsed.total_count !== runs.length) return none;
+    const same = runs.filter((r: { name?: string }) => r?.name === check);
+    const only = same[0];
+    if (same.length !== 1 || only.head_sha !== head || only.status !== "completed" || typeof only.text !== "string") return none;
+    return { check, head, read: true, ...parseEvalMarkers(only.text) };
+  } catch { return none; }
+}
+
+/** The read happens only where it can matter: an enabled mode, a configured eval check and a configuration PR. */
+export async function readEvalFor(config: Pick<SdlcConfig, "configPaths" | "evalCheck" | "mode">, evidence: PrEvidence | undefined, repository: string | undefined, run: SdlcGh): Promise<EvalResult | undefined> {
+  if (!evidence || !repository || !config.evalCheck || evalRequiredChecks(config, evidence).length === 0) return undefined;
+  return readEvalResult(repository, evidence.head, config.evalCheck, run);
+}

package/src/hub/events.ts

@@ -53,7 +53,7 @@ export type HubEvent =
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
-  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
+  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire" | "jcode_acp"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
   | { type: "planning"; by: string; task?: number; release?: number; fields: string[]; revision: number }
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; profile?: string; profileClass?: string; role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string }; pii: boolean; reason?: string; release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }

package/src/hub/external-instance.ts

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+import { readFileSync, lstatSync, mkdirSync } from "node:fs";
+import { types } from "node:util";
+import { atomicPrivateJSON } from "./recovery-store.ts";
+import { realPath } from "./project.ts";
+import { isAbsolute, join } from "node:path";
+import type { ExternalModuleIdentity } from "../adapters/external-modules.ts";
+import type { InstanceConfig } from "./instances.ts";
+
+/** Portable identity only. No catalog epoch, child handle or live-owner authority survives a restart. */
+export interface ExternalInstanceBinding {
+  readonly schema: 1;
+  readonly projectRoot: string;
+  readonly instance: string;
+  readonly kind: string;
+  readonly modulePath: string;
+  readonly sha256: string;
+  readonly api: number;
+  readonly capabilityDigest: string;
+  readonly policyDigest: string;
+  readonly executionCwd: string;
+}
+const KEYS = ["schema", "projectRoot", "instance", "kind", "modulePath", "sha256", "api", "capabilityDigest", "policyDigest", "executionCwd"];
+const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const word = (value: unknown, max: number): value is string => typeof value === "string" && !!value.trim() && Buffer.byteLength(value) <= max && !/[\p{Cc}\p{Cf}]/u.test(value);
+export function validExternalInstanceBinding(value: unknown, projectRoot?: string, instance?: string): value is ExternalInstanceBinding {
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return false;
+  if (Object.values(Object.getOwnPropertyDescriptors(value)).some(field => !Object.hasOwn(field, "value") || !field.enumerable) || Object.getOwnPropertySymbols(value).length) return false;
+  const row = value as Record<string, unknown>;
+  if (Object.keys(row).length !== KEYS.length || Object.keys(row).some(key => !KEYS.includes(key)) || row.schema !== 1 || row.api !== 1) return false;
+  if (!["sha256", "capabilityDigest", "policyDigest"].every(key => typeof row[key] === "string" && /^[a-f0-9]{64}$/.test(row[key] as string))) return false;
+  if (!["instance", "kind"].every(key => typeof row[key] === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(row[key] as string))) return false;
+  if (!word(row.projectRoot, 4096) || !isAbsolute(row.projectRoot) || !word(row.executionCwd, 4096) || !isAbsolute(row.executionCwd) || !word(row.modulePath, 4096) || isAbsolute(row.modulePath) || row.modulePath.split("/").some(part => part === ".." || !part)) return false;
+  return (projectRoot === undefined || row.projectRoot === projectRoot) && (instance === undefined || row.instance === instance);
+}
+export function externalInstanceBinding(identity: ExternalModuleIdentity, instance: string, declaration: InstanceConfig, roles: readonly string[], executionCwd: string): ExternalInstanceBinding {
+  const policyDigest = hash({ kind: declaration.kind, roles: [...roles].sort(), form: "headless", worktree: declaration.worktree, readOnly: declaration.readOnly === true, permission: declaration.permission_mode ?? null });
+  return Object.freeze({ schema: 1, ...identity, instance, kind: declaration.kind, policyDigest, executionCwd });
+}
+export function sameExternalInstanceBinding(left: ExternalInstanceBinding, right: ExternalInstanceBinding): boolean {
+  return KEYS.every(key => left[key as keyof ExternalInstanceBinding] === right[key as keyof ExternalInstanceBinding]);
+}
+
+/** Private host record; native ids are correlation, never liveness/ownership proof. */
+export interface ExternalInstanceRecord { readonly externalInstance: ExternalInstanceBinding; readonly sessionId: string }
+export function externalInstanceStateDir(stateDir: string, instance: string): string {
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(instance)) throw new Error("invalid external instance id");
+  const parent = join(realPath(stateDir), "instances"), result = join(parent, instance);
+  for (const directory of [parent, result]) {
+    try { const info = lstatSync(directory); if (!info.isDirectory() || info.isSymbolicLink() || realPath(directory) !== directory) throw new Error("external instance state namespace changed"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; mkdirSync(directory, { mode: 0o700 }); }
+    const info = lstatSync(directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || realPath(directory) !== directory) throw new Error("external instance state namespace changed");
+  }
+  return result;
+}
+export function readExternalInstanceRecord(stateDir: string, instance: string): ExternalInstanceRecord | undefined {
+  const file = join(stateDir, "instances", instance, "external-instance.json");
+  let raw: unknown;
+  try { const parent = lstatSync(join(stateDir, "instances")); if (!parent.isDirectory() || parent.isSymbolicLink()) throw new Error("external instance state namespace changed"); if (realPath(join(stateDir, "instances", instance)) !== join(realPath(stateDir), "instances", instance)) throw new Error("external instance state namespace changed"); if (!lstatSync(file).isFile() || lstatSync(file).isSymbolicLink()) throw new Error("invalid external instance record"); raw = JSON.parse(readFileSync(file, "utf8")); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw new Error("external instance record is unreadable"); }
+  const row = raw as Partial<ExternalInstanceRecord>;
+  if (!row || Object.keys(row).length !== 2 || !validExternalInstanceBinding(row.externalInstance, undefined, instance) || !word(row.sessionId, 4096)) throw new Error("invalid external instance record");
+  return Object.freeze({ externalInstance: Object.freeze(row.externalInstance), sessionId: row.sessionId });
+}
+export function writeExternalInstanceRecord(stateDir: string, binding: ExternalInstanceBinding, sessionId: string): void {
+  if (!validExternalInstanceBinding(binding) || !word(sessionId, 4096)) throw new Error("invalid external instance record");
+  atomicPrivateJSON(join(externalInstanceStateDir(stateDir, binding.instance), "external-instance.json"), { externalInstance: binding, sessionId });
+}

package/src/hub/facts.ts

@@ -7,6 +7,7 @@ import { sanitize, type PeerId } from "./envelope.ts";
 import { isDenied } from "../local/deny.ts";
 import { hubGitArgv, hubGitEnv } from "./git.ts";
 import { realPath } from "./project.ts";
+import { insideRoot } from "./path-policy.ts";
 
 /**
  * Turn-free facts (issue #108): what changed in an owner's files since it last acknowledged them, as a diff with who
@@ -221,13 +222,22 @@ export class Facts {
       }
     }
     const r = relative(this.root, real);
-    if (!r || r.startsWith("..") || isAbsolute(r) || this.o.repo?.shadow && isHubWritePath(r)) return undefined;
+    // Never trust the resolved name alone (#552, the #541 class): Bun's realpath can name another hardlink of the same file, so the name the
+    // caller gave is judged too. A refusal on either name stands.
+    const typed = relative(this.root, abs);
+    // The resolved name keeps main's original (stricter) test: a directory named `..x` is refused there, as before. Only the typed name this change adds uses the exact segment test.
+    if (!r || r.startsWith("..") || isAbsolute(r) || this.o.repo?.shadow && (isHubWritePath(r) || insideRoot(typed) && isHubWritePath(typed))) return undefined;
     if (this.o.repo?.shadow) {
-      const ignored = Bun.spawnSync(this.gitArgs(["check-ignore", "--no-index", "--quiet", "--", r]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: this.gitEnv(), timeout: 3000 });
-      if (ignored.exitCode !== 1) return undefined; // ignored or unavailable policy is not readable fact evidence
+      // The shadow repository's ignore policy is name-based too, so it is asked about both names: an ignored result, or one that is unavailable (a non-1 exit, a timeout), on either refuses.
+      const insideTyped = !!typed && insideRoot(typed);
+      for (const name of insideTyped && typed !== r ? [r, typed] : [r]) {
+        const ignored = Bun.spawnSync(this.gitArgs(["check-ignore", "--no-index", "--quiet", "--", name]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: this.gitEnv(), timeout: 3000 });
+        if (ignored.exitCode !== 1) return undefined; // ignored or unavailable policy is not readable fact evidence
+      }
     }
-    // Never git's own files, and never what the denylist keeps from every agent.
-    return /(^|\/)\.git(\/|$)/i.test(r) || isDenied(r, this.o.deny ?? []) ? undefined : r;
+    // Never git's own files, and never what the denylist keeps from every agent (the typed name counts as well when it lies inside the project).
+    const named = (name: string) => /(^|\/)\.git(\/|$)/i.test(name) || isDenied(name, this.o.deny ?? []);
+    return named(r) || insideRoot(typed) && named(typed) ? undefined : r;
   }
 
   /**

package/src/hub/folder-trigger.ts

@@ -0,0 +1,223 @@
+import { Database } from "bun:sqlite";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { isDenied } from "../local/deny.ts";
+import { checkCorpusRoot } from "./corpus.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { realPath } from "./project.ts";
+import { folderGlobMatches, MAX_NEW_PER_POLL, type FolderEntry, type FolderRunResult, type FolderScan, type ScannedFile } from "./schedules.ts";
+import { MAX_SOURCE_BYTES, screenRegistration, type SourceRegistry } from "./sources.ts";
+import { matchesPolicy } from "./path-policy.ts";
+
+// agent-hub #512c (hub task #336): the polled folder trigger. Spec: "Schedules and folder triggers (#512)". The hub polls a folder on the schedules timer and never
+// watches it. A file it has not recorded is a new file; the caller registers it as a source and proposes one task. Nothing in this file writes the board or the
+// registry: it reads the disk and keeps its own table in hub.db.
+
+/** Entries a folder may hold before it is refused: a listing is names only, but a folder this size is not an inbox. */
+export const MAX_FOLDER_ENTRIES = 100_000;
+/** Files one poll reads and hashes, and the bytes it reads doing so. Files already recorded at their path, size and mtime cost an `lstat` only. */
+export const MAX_HASH_FILES = 200;
+export const MAX_HASH_BYTES = 256 * 1024 * 1024;
+const CHUNK = 64 * 1024;
+export { MAX_NEW_PER_POLL };
+export type { FolderRunResult, FolderScan, ScannedFile };
+
+export interface FolderPolicy {
+  cwd: string;
+  /** `data.readonly`: declared data folders a trigger may lie inside, besides the project. Project-relative or absolute, as the config holds them. */
+  dataPaths: readonly string[];
+  /** `pii.paths`: a trigger folder under one is refused here. A file that is not under one but whose text matches a PII pattern registers as private: the caller screens it. */
+  piiPaths: readonly string[];
+  /** `local.deny`: substrings, on top of the built-in secrets denylist. */
+  deny: readonly string[];
+}
+
+
+const errno = (error: unknown): string | undefined => (error as NodeJS.ErrnoException | undefined)?.code;
+const beneath = (child: string, parent: string): boolean => child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep);
+const printable = (name: string): string => name.replace(/[\x00-\x1f\x7f]/g, "?").slice(0, 80);
+
+/**
+ * Where a trigger folder may lie: inside the project, or inside a declared data folder. Both sides are `realPath`s, so a link out of either is judged by where it
+ * lands, and a folder that is a vault, on the denylist, or under `pii.paths` is refused by the same check the corpus uses. A reason string, never a throw.
+ */
+export function checkTriggerFolder(entry: FolderEntry, policy: FolderPolicy): { ok: true; real: string } | { ok: false; reason: string } {
+  const checked = checkCorpusRoot(entry.folder, { cwd: policy.cwd, paths: [entry.folder], piiPaths: policy.piiPaths, deny: policy.deny });
+  if (!checked.ok) return { ok: false, reason: checked.reason.replace("a corpus", "a folder trigger").replace("corpus", "folder trigger") };
+  let project: string;
+  const allowed: string[] = [];
+  try {
+    project = realPath(policy.cwd);
+    allowed.push(project);
+    for (const data of policy.dataPaths) { try { allowed.push(realPath(resolve(project, data))); } catch { /* a data folder that is not there allows nothing */ } }
+  } catch { return { ok: false, reason: `${entry.folder} cannot be checked against the project` }; }
+  if (!allowed.some(root => beneath(checked.real, root))) return { ok: false, reason: `${entry.folder} lies outside the project and every declared data.readonly folder` };
+  return { ok: true, real: checked.real };
+}
+
+/**
+ * Read one folder, once, and keep no file's bytes. Regular files directly inside it only (no recursion: a subfolder is not a drop). A name that matches the glob and is
+ * not a dot file is `lstat`ed: a symlink is never read (one that stays inside the folder is skipped as a link, one that leaves as leaving). A file `known` already, by
+ * its real path, size and mtime, returns its recorded hash without being opened. Any other file is opened with O_NOFOLLOW, checked against its `lstat` (size and
+ * inode) and hashed in 64 KiB chunks from that descriptor, so memory stays one chunk wide. At most MAX_HASH_FILES files and MAX_HASH_BYTES bytes are hashed per scan;
+ * the rest are left for the next poll (`truncated`), and the listing is never cut, so a file late in name order is still reached once earlier ones are recorded.
+ * ponytail: a file whose bytes change without its size or mtime changing is not noticed; the upgrade is to hash every poll, which the budget would then have to bound.
+ */
+export function scanFolder(entry: FolderEntry, policy: FolderPolicy, known: (real: string, size: number, mtime: number) => string | undefined = () => undefined, limits: { entries?: number } = {}): FolderScan {
+  const checked = checkTriggerFolder(entry, policy);
+  if (!checked.ok) return { files: [], skipped: [], refused: checked.reason, truncated: false };
+  const folder = checked.real, files: ScannedFile[] = [], skipped: { name: string; reason: string }[] = [];
+  let names: string[];
+  try { names = readdirSync(folder); } catch (error) { return { files: [], skipped: [], refused: `${entry.folder} cannot be listed (${errno(error) ?? "unreadable"})`, truncated: false }; }
+  const maxEntries = limits.entries ?? MAX_FOLDER_ENTRIES; // a parameter so a test can reach the refusal without a hundred thousand files
+  if (names.length > maxEntries) return { files: [], skipped: [], refused: `${entry.folder} holds more than ${maxEntries} entries, which is not an inbox`, truncated: false };
+  names.sort();
+  let truncated = false, hashedFiles = 0, hashedBytes = 0;
+  for (const name of names) {
+    if (!folderGlobMatches(entry.glob, name)) continue;
+    const path = join(folder, name);
+    let stat;
+    try { stat = lstatSync(path); } catch { skipped.push({ name: printable(name), reason: "unreadable" }); continue; }
+    if (stat.isSymbolicLink()) {
+      let target: string | undefined;
+      try { target = realpathSync(path); } catch { /* dangling */ }
+      skipped.push({ name: printable(name), reason: target !== undefined && beneath(target, folder) ? "symlink" : "symlink leaving the folder" });
+      continue;
+    }
+    if (!stat.isFile()) { skipped.push({ name: printable(name), reason: "not a regular file" }); continue; }
+    if (isDenied(path, [...policy.deny])) { skipped.push({ name: printable(name), reason: "on the denylist" }); continue; }
+    if (stat.size > MAX_SOURCE_BYTES) { skipped.push({ name: printable(name), reason: `over the ${MAX_SOURCE_BYTES} byte source cap` }); continue; }
+    const mtime = Math.floor(stat.mtimeMs);
+    const recorded = known(path, stat.size, mtime);
+    if (recorded !== undefined) { files.push({ real: path, name, size: stat.size, mtime, sha256: recorded, seen: true }); continue; }
+    if (hashedFiles >= MAX_HASH_FILES || hashedFiles > 0 && hashedBytes + stat.size > MAX_HASH_BYTES) { truncated = true; continue; }
+    const sha256 = hashFile(path, stat.size, stat.ino);
+    if (sha256 === undefined) { skipped.push({ name: printable(name), reason: "changed while it was read" }); continue; }
+    hashedFiles++; hashedBytes += stat.size;
+    files.push({ real: path, name, size: stat.size, mtime, sha256 });
+  }
+  return { folder, files, skipped, truncated };
+}
+
+/** The SHA-256 of a regular file, read in chunks from a descriptor opened without following a link; undefined when it changed under the read or cannot be read. */
+function hashFile(path: string, size: number, ino: number): string | undefined {
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); } catch { return undefined; }
+  try {
+    const open = fstatSync(fd);
+    if (!open.isFile() || open.size !== size || open.ino !== ino) return undefined;
+    const hash = createHash("sha256"), chunk = Buffer.alloc(Math.min(CHUNK, Math.max(size, 1)));
+    let total = 0;
+    for (;;) { const n = readSync(fd, chunk, 0, chunk.length, total); if (!n) break; hash.update(chunk.subarray(0, n)); total += n; }
+    return total === size ? hash.digest("hex") : undefined;
+  } catch { return undefined; } finally { closeSync(fd); }
+}
+
+/**
+ * The bytes of a scanned file, for the one file being registered now: read again from a descriptor opened without following a link, and returned only when they still
+ * hash to what the scan recorded. A file that changed since is undefined, so it is tried again on the next poll under its new content. At most one file is in memory.
+ */
+export function readScanned(file: Pick<ScannedFile, "real" | "size" | "sha256">): Buffer | undefined {
+  let fd: number;
+  try { fd = openSync(file.real, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); } catch { return undefined; }
+  try {
+    const open = fstatSync(fd);
+    if (!open.isFile() || open.size !== file.size || open.size > MAX_SOURCE_BYTES) return undefined;
+    const bytes = Buffer.alloc(open.size);
+    let got = 0;
+    while (got < bytes.length) { const n = readSync(fd, bytes, got, bytes.length - got, got); if (!n) break; got += n; }
+    return got === open.size && createHash("sha256").update(bytes).digest("hex") === file.sha256 ? bytes : undefined;
+  } catch { return undefined; } finally { closeSync(fd); }
+}
+
+/** What registering a scanned file needs from the host: the registry, the PII policy, the routing's patterns and the text projection. */
+export interface FolderRegistration {
+  registry: Pick<SourceRegistry, "add">;
+  cwd: string;
+  piiPaths: readonly string[];
+  /** Read at each call: the routing can be reloaded between polls. */
+  piiPatterns: () => readonly string[];
+  /** The projected text of a file's bytes by its extension, or undefined when no converter handles it. */
+  project?: (extension: string, bytes: Buffer) => string | undefined;
+}
+
+/**
+ * Register one scanned file as a source, the same two steps `ahub source add` takes: one decision about privacy, then the registry. The scan kept no bytes, so the file is
+ * read again here and refused (a throw, so the file is tried again on the next poll as what it has become) when it no longer hashes to what the scan saw. A file under
+ * `pii.paths`, or whose text matches a PII pattern, is a private source. This is the function the daemon calls; the tests call it too.
+ */
+export function registerScanned(file: ScannedFile, host: FolderRegistration): { id: string; private: boolean } {
+  const bytes = readScanned(file);
+  if (!bytes) throw new Error("the file changed or became unreadable before it was registered");
+  const extension = /\.[A-Za-z0-9]{1,16}$/.exec(file.name)?.[0]?.toLowerCase() ?? "";
+  const verdict = screenRegistration({ bytes, kind: "file", path: file.real }, {
+    piiPaths: [...host.piiPaths], piiPatterns: [...host.piiPatterns()], cwd: host.cwd, matchesPolicy,
+    ...(host.project ? { project: data => extension ? host.project!(extension, data) : undefined } : {}),
+  });
+  const added = host.registry.add({ bytes, kind: "file", origin: file.real, private: verdict.private, ...(verdict.text !== undefined ? { text: verdict.text } : {}) });
+  return { id: added.id, private: added.private };
+}
+
+export interface FolderSeenRow { trigger: string; real_path: string; size: number; mtime: number; sha256: string; task: number | null; at: number }
+
+/**
+ * `folder_seen` in hub.db: what each trigger has already acted on, by real path, size, mtime and SHA-256. A file is NEW to a trigger when its content hash was not
+ * recorded for it. A rename keeps the hash and a touch keeps the hash too, so neither proposes again; the same bytes under another name are the same file to the
+ * trigger (the source registry holds one record per hash as well). A path whose content changed has a new hash, so it is a new file: different bytes.
+ */
+export class FolderStore {
+  private readonly db: Database;
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db.run("CREATE TABLE IF NOT EXISTS folder_seen (trigger TEXT NOT NULL, real_path TEXT NOT NULL, size INTEGER NOT NULL, mtime INTEGER NOT NULL, sha256 TEXT NOT NULL, task INTEGER, at INTEGER NOT NULL, PRIMARY KEY (trigger, real_path, sha256))");
+    this.db.run("CREATE INDEX IF NOT EXISTS folder_seen_hash ON folder_seen (trigger, sha256)");
+    this.db.run("CREATE TABLE IF NOT EXISTS folder_poll (trigger TEXT PRIMARY KEY, started INTEGER NOT NULL, baselined INTEGER NOT NULL DEFAULT 0, last_poll INTEGER, last_error TEXT)");
+  }
+  /**
+   * A trigger's baseline is the files already in its folder when it starts: they are recorded and propose nothing, so adding a trigger to a full inbox does not flood the
+   * board. A big folder takes several polls to hash, so the baseline is complete only when a poll finished the whole folder (`markBaselined`); until then every file a poll
+   * reads is recorded and none proposes.
+   */
+  baselined(trigger: string): boolean {
+    const row = this.db.query("SELECT baselined FROM folder_poll WHERE trigger = ?").get(trigger) as { baselined: number } | null;
+    return row?.baselined === 1;
+  }
+  begin(trigger: string, now: number): void { this.db.query("INSERT OR IGNORE INTO folder_poll(trigger, started) VALUES(?, ?)").run(trigger, now); }
+  markBaselined(trigger: string, now: number): void { this.db.query("UPDATE folder_poll SET baselined = 1, last_poll = ? WHERE trigger = ?").run(now, trigger); }
+  /** The recorded hash of a file at this exact path, size and mtime, or undefined. Such a file need not be read again. */
+  known(trigger: string, real: string, size: number, mtime: number): string | undefined {
+    const row = this.db.query("SELECT sha256 FROM folder_seen WHERE trigger = ? AND real_path = ? AND size = ? AND mtime = ? ORDER BY at DESC LIMIT 1").get(trigger, real, size, mtime) as { sha256: string } | null;
+    return row?.sha256;
+  }
+  /** The last poll's time and error. A trigger that has not begun (its folder was refused every time so far) has no row, and none is made: refusing is not beginning. */
+  polled(trigger: string, now: number, error?: string): void { this.db.query("UPDATE folder_poll SET last_poll = ?, last_error = ? WHERE trigger = ?").run(now, error?.slice(0, 200) ?? null, trigger); }
+  isNew(trigger: string, sha256: string): boolean {
+    return !this.db.query("SELECT 1 FROM folder_seen WHERE trigger = ? AND sha256 = ? LIMIT 1").get(trigger, sha256);
+  }
+  record(trigger: string, file: Pick<ScannedFile, "real" | "size" | "mtime" | "sha256">, task: number | null, now: number): void {
+    this.db.query("INSERT OR REPLACE INTO folder_seen(trigger, real_path, size, mtime, sha256, task, at) VALUES(?, ?, ?, ?, ?, ?, ?)").run(trigger, file.real, file.size, file.mtime, file.sha256, task, now);
+  }
+  /**
+   * Record where a file whose content the trigger already knows (a rename, a touch, a copy of earlier bytes) is NOW, by path, size and mtime, so the next scan finds it with
+   * `known` and does not hash it again. It keeps the task the content already has and proposes nothing. Without this a pile of such files would be hashed on every poll and
+   * spend the whole hash budget ahead of a genuinely new file, which would then wait forever.
+   */
+  observe(trigger: string, file: Pick<ScannedFile, "real" | "size" | "mtime" | "sha256">, now: number): void {
+    const prior = this.db.query("SELECT task FROM folder_seen WHERE trigger = ? AND sha256 = ? AND task IS NOT NULL ORDER BY at LIMIT 1").get(trigger, file.sha256) as { task: number } | null;
+    this.record(trigger, file, prior?.task ?? null, now);
+  }
+  rows(trigger?: string): FolderSeenRow[] {
+    return (trigger === undefined ? this.db.query("SELECT * FROM folder_seen ORDER BY trigger, at, real_path").all() : this.db.query("SELECT * FROM folder_seen WHERE trigger = ? ORDER BY at, real_path").all(trigger)) as FolderSeenRow[];
+  }
+  /** A trigger removed from the config keeps no rows. */
+  prune(keep: readonly string[]): void {
+    for (const row of this.db.query("SELECT DISTINCT trigger FROM folder_seen UNION SELECT trigger FROM folder_poll").all() as { trigger: string }[]) {
+      if (keep.includes(row.trigger)) continue;
+      this.db.query("DELETE FROM folder_seen WHERE trigger = ?").run(row.trigger);
+      this.db.query("DELETE FROM folder_poll WHERE trigger = ?").run(row.trigger);
+    }
+  }
+  close(): void { try { this.db.close(); } catch { /* already closed */ } }
+}

package/src/hub/hub-tools.ts

@@ -110,6 +110,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, findings: reviewFindings, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet; when the review request lists acceptance criteria, start an item with its id (\"AC1: what is missing\") so the verdict names it" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
+  tool("hub_source_read", "Read a registered source snapshot. Unicode character range, at most 32 KiB of sanitized UTF-8 text with next character offset. Private sources return only id, kind and private unless called by the on-prem worker inside a PII task. Excluded from capture.", { id: { type: "string", pattern: "^src:[0-9a-f]{16}$" }, range: { type: "object", properties: { offset: { type: "integer", minimum: 0 }, length: { type: "integer", minimum: 1 } }, required: ["offset", "length"], additionalProperties: false } }, ["id"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
   tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Symbol starts also include optional current-head one-hop code neighbours as derived SHA-stamped edges; unknown coverage is explicit. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
@@ -168,7 +169,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_status"]);
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;

package/src/hub/inference.ts

@@ -47,15 +47,19 @@ export class Inference {
    * `interactive`: a person is waiting for this one answer (`ahub ask`). It gets its own, longer clock and neither obeys
    * nor trips the backoff that protects the delivery path, so a slow answer cannot switch off triage and digests.
    */
-  async complete(system: string, user: string, maxTokens: number, opts: { interactive?: boolean; timeoutMs?: number } = {}): Promise<string | undefined> {
+  async complete(system: string, user: string, maxTokens: number, opts: { interactive?: boolean; timeoutMs?: number; onCampusOnly?: boolean; allowed?: () => boolean } = {}): Promise<string | undefined> {
     if (!this.cfg.enabled || (!opts.interactive && Date.now() < this.offUntil)) return undefined;
+    try { if (opts.allowed?.() === false) return undefined; } catch { return undefined; }
+    // Pin the host-selected on-prem fixed model before any gateway await.
+    let pinnedModel: string | undefined;
+    try { pinnedModel = opts.onCampusOnly ? this.d.fixedModel() : undefined; } catch { return undefined; }
     const abort = new AbortController();
     const limit = opts.timeoutMs ?? this.d.timeoutMs ?? TIMEOUT_MS;
     const quiet = !!opts.interactive;
     let timer: ReturnType<typeof setTimeout> | undefined;
     // One clock over everything, the gateway probe included, not only the model call.
     const timeout = new Promise<"timeout">((resolve) => (timer = setTimeout(() => (abort.abort(), resolve("timeout")), limit)));
-    const result = await Promise.race([this.run(system, user, maxTokens, abort.signal, quiet), timeout]);
+    const result = await Promise.race([this.run(system, user, maxTokens, abort.signal, quiet, opts.onCampusOnly, pinnedModel, opts.allowed), timeout]);
     clearTimeout(timer);
     if (result === "timeout") return quiet ? undefined : this.backOff(`no answer within ${limit / 1000} s`);
     return result;
@@ -68,14 +72,16 @@ export class Inference {
     return undefined;
   }
 
-  private async run(system: string, user: string, maxTokens: number, signal: AbortSignal, quiet = false): Promise<string | undefined> {
+  private async run(system: string, user: string, maxTokens: number, signal: AbortSignal, quiet = false, onCampusOnly = false, pinnedModel?: string, allowed?: () => boolean): Promise<string | undefined> {
     try {
       // No gateway configured is the normal state of a fresh install; one that is configured but unreachable costs a
       // probe every time, so both back off.
       if (!(await this.d.omni.base())) return this.backOff("no gateway configured or reachable", quiet);
+      if (signal.aborted || allowed?.() === false) return undefined;
       const messages = [{ role: "system" as const, content: system }, { role: "user" as const, content: user }];
-      const body = { model: this.d.fixedModel(), messages, max_tokens: maxTokens };
-      const res = await this.d.omni.chat(body, { signal });
+      const body = { model: pinnedModel ?? this.d.fixedModel(), messages, max_tokens: maxTokens };
+      const res = await this.d.omni.chat(body, { signal, ...(onCampusOnly ? { onCampusOnly: true } : {}) });
+      if (allowed?.() === false) return undefined;
       return res.message.content?.trim() || undefined;
     } catch (e) {
       return signal.aborted ? undefined : this.backOff((e as Error).message, quiet);
@@ -127,6 +133,15 @@ export class Inference {
     return CLASSES.find((c) => c === word);
   }
 
+  /**
+   * #334: the hub model's JSON split of a person's request. The person waits for this one answer, so it is `interactive`: its own, longer clock that
+   * neither obeys nor trips the delivery backoff. The answer is parsed and validated by the caller (`parseIntakeSplit`), never trusted here.
+   */
+  async split(system: string, user: string, opts: { campusOnly?: boolean } = {}): Promise<string | undefined> {
+    // `campusOnly`: the request is PII, so transport itself refuses the Access endpoint, as the PII screen does, whatever an earlier check saw.
+    return this.complete(system, user, 3000, { interactive: true, timeoutMs: 60_000, ...(opts.campusOnly ? { onCampusOnly: true } : {}) });
+  }
+
   /** A closed escalation verdict, or no verdict when inference is unavailable or malformed. */
   async escalate(conversation: Conversation, turn: number): Promise<EscalationVerdict | undefined> {
     const request = buildEscalationJudgeRequest(conversation, turn);