@staix/agent-hub 0.20.0 → 0.21.0

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);

package/src/hub/instance-config.ts

@@ -2,10 +2,11 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createProjectAdapterCatalog, defaultPeerRoles, definitionOf, type ProjectAdapterCatalog, type AdapterDefinition } from "../adapters/registry.ts";
 import { readAdapterModuleDeclarations, type AdapterModuleDeclaration } from "../adapters/external-modules.ts";
-import { externalMetadataDefinitions } from "../adapters/external-metadata.ts";
+import { externalMetadataDefinitions, moduleArray, moduleDataObject, moduleText } from "../adapters/external-metadata.ts";
 import { readControl, stateDirFor } from "./control-client.ts";
 import { conductorPeer } from "./conductor.ts";
 import { configRefusal } from "./config-trust.ts";
+import { isPermissionMode } from "./permission-mode.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
 
 export const INSTANCE_CONFIG_FILES = ["config.json", "config.local.json"] as const;
@@ -20,13 +21,43 @@ export function readInstanceConfigLayers(cwd: string): InstanceConfigLayer[] {
 }
 
 /** Declaration authority is file provenance, never a suffix or a claim made by a native child. */
+export interface DeclaredExternalInstance {
+  readonly id: string;
+  readonly kind: string;
+  readonly availability: "declared-unknown" | "refused";
+  readonly refusalCode: "catalog-unavailable" | "module-refused" | "kind-unavailable";
+}
 export interface InstanceRoleConfig {
   adapter_modules?: readonly AdapterModuleDeclaration[];
   adapters?: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
   instances?: InstancesConfig;
+  /** Unresolved or refused module declarations, excluded from executable policy. */
+  declaredExternalInstances?: readonly DeclaredExternalInstance[];
   catalog: ProjectAdapterCatalog;
   ignored: string[];
 }
+/** Keep valid dormant policy on disk, but never admit it through an unavailable module's identity. */
+export function withoutInertInstancePolicy(raw: Record<string, unknown>, rows: readonly DeclaredExternalInstance[] = []): Record<string, unknown> {
+  if (!rows.length) return raw;
+  const ids = new Set(rows.flatMap(row => [row.id, row.kind]));
+  const result = { ...raw };
+  for (const key of ["permission_modes", "peers"] as const) {
+    if (raw[key] === undefined) continue;
+    const block = moduleDataObject(raw[key]);
+    result[key] = Object.fromEntries(Object.entries(block).filter(([id, value]) => {
+      if (!ids.has(id)) return true;
+      if (key === "permission_modes") {
+        if (!isPermissionMode(value)) throw new Error(`permission_modes.${id}: invalid dormant mode`);
+      } else {
+        const settings = moduleDataObject(value);
+        if (Object.keys(settings).some(field => field !== "start_mode") || settings.start_mode !== undefined && settings.start_mode !== "headless") throw new Error(`peers.${id}: invalid dormant headless setting`);
+      }
+      return false;
+    }));
+  }
+  return result;
+}
+
 export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd), externalDefinitions?: readonly AdapterDefinition[]): InstanceRoleConfig {
   const moduleConfig = readAdapterModuleDeclarations(cwd, layers);
   const ignored: string[] = [...moduleConfig.ignored];
@@ -47,8 +78,40 @@ export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigL
     external = externalMetadataDefinitions(metadata);
   }
   const catalog = createProjectAdapterCatalog(adapters, external);
-  const instances = validateInstances(rawInstances, catalog);
-  return { ...(moduleConfig.modules.length ? { adapter_modules: moduleConfig.modules } : {}), ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), catalog, ignored };
+  // A descriptor on disk is display evidence only. It cannot turn module kinds into executable
+  // definitions or establish live policy. Only the daemon's explicit captured definitions can.
+  const runtimeDefinitions = new Set(externalDefinitions?.filter(definition => typeof definition.start.create === "function"));
+  const declaredExternalInstances: DeclaredExternalInstance[] = [];
+  let executableInstances = rawInstances;
+  if (moduleConfig.modules.length && rawInstances !== undefined) {
+    const entries = moduleDataObject(rawInstances);
+    if (Object.keys(entries).length > 64) throw new Error("instances: at most 64 extra instances are supported");
+    const executable: Record<string, unknown> = Object.create(null);
+    for (const [id, value] of Object.entries(entries)) {
+      const row = moduleDataObject(value), kind = row.kind;
+      const definition = typeof kind === "string" ? catalog.definitionOf(kind) : undefined;
+      const inert = !definition || catalog.externalDefinitions.includes(definition) && !runtimeDefinitions.has(definition);
+      if (!inert) { executable[id] = value; continue; }
+      if (!/^[a-z][a-z0-9-]{0,31}$/.test(id) || typeof kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(kind)
+        || !id.startsWith(`${kind}-`) || !/^[a-z0-9][a-z0-9-]*$/.test(id.slice(kind.length + 1))) throw new Error("instances: invalid unresolved module instance declaration");
+      if (Object.keys(row).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "readOnly"].includes(key))) throw new Error("instances: unsupported external instance field");
+      if (Object.hasOwn(row, "roles")) {
+        const roles = moduleArray(row.roles, 3);
+        if (roles.some(role => typeof role !== "string" || !["implementer", "verifier", "reviewer"].includes(role)) || new Set(roles).size !== roles.length) throw new Error("instances: unsupported external instance role");
+      }
+      if (Object.hasOwn(row, "start_mode") && row.start_mode !== "headless") throw new Error("instances: external instances require headless mode");
+      if (Object.hasOwn(row, "readOnly") && typeof row.readOnly !== "boolean") throw new Error("instances: readOnly must be a boolean");
+      if (Object.hasOwn(row, "permission_mode") && (typeof row.permission_mode !== "string" || !["ask", "ask-when-needed", "never-ask"].includes(row.permission_mode))) throw new Error("instances: unknown permission mode");
+      if (row.readOnly === true && Object.hasOwn(row, "permission_mode")) throw new Error("instances: read-only instances cannot select a permission mode");
+      if (Object.hasOwn(row, "worktree")) moduleText(row.worktree, 4096);
+      declaredExternalInstances.push(Object.freeze(externalDefinitions === undefined
+        ? { id, kind, availability: "declared-unknown", refusalCode: "catalog-unavailable" }
+        : { id, kind, availability: "refused", refusalCode: "kind-unavailable" }));
+    }
+    executableInstances = executable;
+  }
+  const instances = validateInstances(executableInstances, catalog);
+  return { ...(moduleConfig.modules.length ? { adapter_modules: moduleConfig.modules } : {}), ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), ...(declaredExternalInstances.length ? { declaredExternalInstances: Object.freeze(declaredExternalInstances) } : {}), catalog, ignored };
 }
 
 /** Capture ordinary role policy and trusted instance declarations together, without loading daemon configuration. */
@@ -63,6 +126,9 @@ export function readInstanceRoleConfig(cwd: string, layers: readonly InstanceCon
       for (const [id, list] of Object.entries(raw.roles as Record<string, string[]>)) roles[id] = [...list];
     }
   }
+  // Unresolved rows and display-only module definitions grant no roles through id or kind aliases.
+  for (const row of declarationConfig.declaredExternalInstances ?? []) { delete roles[row.id]; delete roles[row.kind]; }
+  for (const definition of declarationConfig.catalog.externalDefinitions) delete roles[definition.kind];
   conductorPeer(roles);
   return { ...declarationConfig, roles };
 }

package/src/hub/instance-execution.ts

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import type { ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { hubGitSync } from "./git.ts";
 import { realPath } from "./project.ts";
-import { validateInstances, type InstancesConfig } from "./instances.ts";
+import { isPlannerOnly, validateInstances, type InstancesConfig } from "./instances.ts";
 
 const refuse = (reason: string): never => { throw new Error(`instance execution workspace refused: ${reason}`); };
 // #225: this runs synchronously on the daemon's event loop (an extra-instance start, turn_revert), and a resolution makes up to four git
@@ -31,8 +31,12 @@ export function resolveInstanceExecutionCwd(projectRoot: string, id: string, dec
   const git = gitWithin(budgetMs, clock, run);
   const declaration = validateInstances(declarations, adapterCatalog)[id];
   if (!declaration) return refuse("extra instance is not declared");
+  if (declaration.worktree && adapterCatalog.definitionOf(id, declarations)?.start.daemonPort === "codex-appserver" && isPlannerOnly(roles)) return refuse("a planner-only app-server instance plans on the project checkout; worktree is not supported");
+  const moduleInstance = adapterCatalog.externalDefinitions.some(definition => definition.kind === declaration.kind);
   const implementer = roles.includes("implementer");
+  const writing = moduleInstance ? declaration.readOnly !== true : implementer;
   if (!declaration.worktree) {
+    if (moduleInstance) return refuse("every external instance requires its own managed worktree");
     if (implementer) return refuse("an extra implementer requires an explicit managed worktree");
     return projectRoot;
   }
@@ -56,7 +60,7 @@ export function resolveInstanceExecutionCwd(projectRoot: string, id: string, dec
   if (commonDirectory(git, root) !== commonDirectory(git, cwd)) return refuse("worktree belongs to a different Git repository");
   const top = git(cwd, ["rev-parse", "--show-toplevel"]).replace(/\n$/, "");
   if (realPath(top) !== cwd) return refuse("directory is not the registered worktree root");
-  if (implementer && !matches[0]!.some(field => field.startsWith("branch refs/heads/") && field.length > "branch refs/heads/".length)) return refuse("an implementer worktree requires an attached branch");
+  if (writing && !matches[0]!.some(field => field.startsWith("branch refs/heads/") && field.length > "branch refs/heads/".length)) return refuse(moduleInstance ? "a potentially writing external instance requires an attached branch" : "an implementer worktree requires an attached branch");
   // ponytail: this read cannot bind the branch to a task or make path swaps atomic; task/start authority must recheck before effects.
   return cwd;
 }