@staix/agent-hub 0.18.0 → 0.19.0

package/src/hub/operational-authority.ts

@@ -41,6 +41,12 @@ export function conductorOperation(command:string,args:readonly string[]): Condu
 }
 
 
+/** Only a failed conductor/operational authority fence carries this marker, never an ordinary operation error. */
+export class OperationalAuthorityError extends Error {
+  readonly code = "AHUB_OPERATIONAL_AUTHORITY";
+  constructor(message:string,readonly scope:"conductor"|"person"|"operational"="operational") { super(message); }
+}
+
 export const OPERATIONAL_PERSON_GUIDANCE="the person runs it in ahub console or a terminal";
 export function operationalRefusal(peer:string,command:string):string {
   return `${peer} cannot run ahub ${command}; ${OPERATIONAL_PERSON_GUIDANCE}; this operation requires the explicit conductor role`;
@@ -54,6 +60,7 @@ export function operationalRequestLabel(value:unknown):string|undefined {
     return message.op==="orphans"?"doctor orphans kill":message.op==="logs"||message.op==="export"?message.op:"unknown";
   }
   if(message.t==="peer_stop")return "stop";
+  if(message.t==="task" && message.op==="hub_task_cancel")return "task cancel";
   if(message.t==="queue" && typeof message.op==="string" && ["show","resolve","discard"].includes(message.op))return `queue ${message.op}`;
   if(message.t==="settings_set"||message.t==="settings_preview")return "settings set";
   return undefined;

package/src/hub/operational-view.ts

@@ -87,16 +87,12 @@ const positive=(value:unknown):value is number=>Number.isSafeInteger(value) && (
 
 /** Bind the existing task/privacy projections once per read; no private title or path leaves this closure. */
 export function operationalView(ports:OperationalViewPorts) {
-  const tasks=new Map(ports.tasks.map(task=>[task.id,task]));
+  const publicTasks=new Set<number>();
   const privateTitles:string[]=[];
-  // ponytail: a complete privacy inventory is capped at 500 tasks; indexed scoped log records can extend it.
-  let known=ports.tasks.length<=500;
-  try {for(const task of ports.tasks.slice(0,500)) {const view=ports.publicView(task);if(ports.isPii(task) || view.title!==task.title) privateTitles.push(task.title);}} catch {known=false;}
-  const safeTask=(id:number):boolean=>{
-    const task=tasks.get(id);
-    if (!task) return false;
-    try {return !ports.isPii(task) && ports.publicView(task).title===task.title;} catch {return false;}
-  };
+  // The caller caches this complete inventory by board/privacy revision; there is no task-count display ceiling.
+  let known=true;
+  try {for(const task of ports.tasks) {const view=ports.publicView(task);if(ports.isPii(task) || view.title!==task.title) privateTitles.push(task.title);else publicTasks.add(task.id);}} catch {known=false;}
+  const safeTask=(id:number):boolean=>known && publicTasks.has(id);
   const safeText=(text:string):boolean=>{
     if (!known || Buffer.byteLength(text)>65536 || privateTitles.some(title=>title && text.includes(title))) return false;
     try {return ports.publicMetadataText(text);} catch {return false;}
@@ -137,5 +133,5 @@ export function operationalView(ports:OperationalViewPorts) {
       return JSON.parse(text,(_key,item)=>typeof item==="string"?sanitize(item):item) as Record<string,unknown>;
     } catch {return withheld;}
   };
-  return {line,event,complete:known};
+  return {line,event,complete:known,...(!known?{incompleteReason:"privacy inventory unavailable"}: {})};
 }

package/src/hub/read-only-shell-proof.ts

@@ -1,5 +1,4 @@
 import { accessSync, constants, lstatSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -7,10 +6,11 @@ import { guardPath, type ShellExecutionCheck } from "../local/tools.ts";
 import { hostExecutable } from "./host-executable.ts";
 import { hubGitArgv, hubGitEnv } from "./git.ts";
 import { realPath } from "./project.ts";
-import { readOnlyShellForm, type ReadOnlyProgram } from "./read-only-shell.ts";
+import { parseSimpleShell, readOnlyShellForm, type ReadOnlyProgram } from "./read-only-shell.ts";
+import { hostShellEnvironment } from "../local/shell-environment.ts";
 
 export interface ShellProofOptions { root:string; projectRoot?:string; deny:string[]; readOnly?:string[]; env?:Record<string,string> }
-export interface ReadOnlyShellProof { fingerprint:string; program:ReadOnlyProgram }
+export interface ReadOnlyShellProof { fingerprint:string; program:ReadOnlyProgram; executable:string; argv:readonly string[] }
 const within=(root:string,path:string)=>{const p=relative(root,path);return p==="" || p!==".."&&!p.startsWith("../")&&!isAbsolute(p);};
 function firstProgram(name:string,root:string,path:string):string|undefined {
   if(path.length>16384)return undefined;
@@ -49,14 +49,15 @@ export function proveReadOnlyShell(input:unknown,options:ShellProofOptions,curre
     const root=realPath(options.root),projectRoot=realPath(options.projectRoot??options.root),names:string[]=[root,projectRoot];
     const form=readOnlyShellForm(args.command,root,(path,base=root)=>{if(path.split("/").includes(".."))throw new Error("ambiguous parent traversal");const lexical=resolve(base,path),canonical=guardPath({cwd:root,deny:options.deny,readOnly:options.readOnly},lexical,"read");names.push(lexical,canonical);return canonical;});
     if(!form || !current())return undefined;
-    const env={PATH:process.env.PATH??"/usr/bin:/bin",HOME:homedir(),LANG:process.env.LANG??"en_US.UTF-8",TERM:"dumb",...options.env};
+    const env=hostShellEnvironment(options.env);
     const lexical=firstProgram(form.program,root,env.PATH);if(!lexical || within(root,lexical) || within(projectRoot,lexical))return undefined;
     const executable=hostExecutable(form.program,root,env.PATH);if(realPath(lexical)!==executable || within(projectRoot,executable) || !current())return undefined;
     if(form.gitCwd && !gitHelpersUnconfigured(executable,form.gitCwd,env,current))return undefined;
     // ponytail: this screens the declared helper-bearing config keys and explicit diff/textconv flags; other config-mediated helpers need dedicated audited forms before extending the allowlist.
     const paths=new Set([...names.flatMap(name=>ancestors(name,root)),...ancestors(lexical,"/"),...ancestors(executable,"/")]);
-    const fingerprint=createHash("sha256").update(JSON.stringify([root,projectRoot,args.command,env.PATH,lexical,executable,[...paths].map(path=>stamp(path,path===lexical||path===executable))])).digest("hex");
-    return current()?{fingerprint,program:form.program}:undefined;
+    const fingerprint=createHash("sha256").update(JSON.stringify([root,projectRoot,args.command,env,lexical,executable,[...paths].map(path=>stamp(path,path===lexical||path===executable))])).digest("hex");
+    const argv=parseSimpleShell(args.command)!.words.slice(1);
+    return current()?{fingerprint,program:form.program,executable,argv}:undefined;
   } catch {return undefined;}
 }
 interface Decision { command:string; current:()=>boolean; proof?:ReadOnlyShellProof }

package/src/hub/review-scope.ts

@@ -0,0 +1,13 @@
+/**
+ * #852: a reviewer's review scope. `full` reads the code, runs the affected tests and reads CI; `code` reads the code only, because its sandbox
+ * cannot run tests or read CI. AC3 (amended 2026-10-26) is structural, never a reading of free text: a `code` reviewer's changes_requested is always
+ * recorded, and one with no open structured finding is recorded as evidence-only (see Tasks.review).
+ */
+export type ReviewScope = "full" | "code";
+export const REVIEW_SCOPES: readonly ReviewScope[] = ["full", "code"];
+export const isReviewScope = (value: unknown): value is ReviewScope => value === "full" || value === "code";
+
+/** The one review-request line for a `code` reviewer (AC2). Fixed text: no hub or PR content is interpolated. */
+export const CODE_SCOPE_LINE = "Your sandbox cannot run tests or read CI: review the code against the plan. The merger gates on exact-head CI (#852). Findings are only for defects in the reviewed code, docs or tests. A missing check result, CI result, test run or PR/branch identity is an evidence request: put it in unmet, never in findings. Report every code defect as a structured finding with an id (hub_review findings, disposition open); a verdict with no open finding is recorded as evidence-only and does not count as a rejection.";
+/** The one task notice the conductor gets when a code-scope reviewer's verdict is recorded as evidence-only (ids only, never text). */
+export const evidenceOnlyNotice = (task: number, reviewer: string): string => `Task #${task}: a code-scope review by ${reviewer} was recorded as evidence-only (no open finding) and the task returned to its owner. Take the review.`;

package/src/hub/sdlc-metrics.ts

@@ -11,8 +11,8 @@ export type BandTier = typeof BAND_TIERS[number];
 export interface MetricTask {
   id: number;
   private?: boolean;
-  /** `requestHead` is the head a `done` asked review for (reviewCost.head); `verdictHead` the head a verdict was bound to (reviewFindings.head). Compared for equality only, never printed. */
-  history: { at: number; event: string; requestHead?: string; verdictHead?: string }[];
+  /** `evidenceOnly` marks a code-scope verdict with no open finding (#852): it is not a rework round. `requestHead` is the head a `done` asked review for (reviewCost.head); `verdictHead` the head a verdict was bound to (reviewFindings.head). Compared for equality only, never printed. */
+  history: { at: number; event: string; requestHead?: string; verdictHead?: string; evidenceOnly?: true }[];
 }
 
 /** Per-task values; `null` is unknown. */
@@ -98,6 +98,8 @@ export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciRerun
   const spec = first(view, ["spec accepted"]);
   const plan = spec ? first(view, ["plan reviewed"], spec.at) : undefined;
   const verdict = accepted ? first(view, VERDICTS, accepted.at) : first(view, VERDICTS);
+  // Evidence-only still ends the actual wait for a first review, but says nothing about whether the work passed.
+  const substantiveVerdict = history.find(entry => entry.at >= (accepted?.at ?? -Infinity) && VERDICTS.includes(entry.event) && entry.evidenceOnly !== true);
   const dones = history.filter(entry => entry.event === "done");
   const ci = first(view, ["check passed", "check failed"]);
   const approvedAt = history.find(entry => entry.event === "approved")?.at ?? null;
@@ -108,10 +110,10 @@ export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciRerun
     acceptance_to_plan_ms: spec && plan ? plan.at - spec.at : null,
     acceptance_to_first_review_ms: accepted && verdict ? verdict.at - accepted.at : null,
     acceptance_to_merge_ms: accepted && extra.mergedAt !== undefined && Number.isFinite(extra.mergedAt) && extra.mergedAt >= accepted.at ? extra.mergedAt - accepted.at : null,
-    first_pass_approval: verdict ? (verdict.event === "approved" ? 1 : 0) : null,
+    first_pass_approval: substantiveVerdict ? (substantiveVerdict.event === "approved" ? 1 : 0) : null,
     // Rework grows with every round, so it is a value only once the task is approved: a task still in flight has no final one, and a
     // provisional point would move at each verdict and could start a second breach episode inside one shift.
-    rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested").length : null,
+    rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested" && entry.evidenceOnly !== true).length : null,
     first_pass_check: ci ? (ci.event === "check passed" ? 1 : 0) : null,
     same_head_ci_reruns: extra.ciReruns === undefined ? null : extra.ciReruns,
     stale_head_re_reviews: approvedAt !== null ? staleHeadRounds(history) : null,

package/src/hub/task-shell-command.ts

@@ -0,0 +1,85 @@
+import { parseSimpleShell } from "./read-only-shell.ts";
+
+/** Short branch names from host evidence, never from the permission request. */
+export interface TaskShellBinding { branch: string; defaultBranch: string }
+export interface TaskShellCommand {
+  kind: "check" | "build" | "test" | "add" | "commit" | "push" | "pr-view" | "pr-checks" | "pr-create";
+  program: "scripts/check.sh" | "bun" | "git" | "gh";
+  argv: readonly string[];
+  /** Original literal path operands. The host must guard them under its verified execution root. */
+  paths: readonly string[];
+}
+
+export function shortBranch(value: unknown): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/.test(value)
+    && value !== "HEAD" && !value.startsWith("refs/") && !value.includes("..") && !value.includes("//")
+    && !value.endsWith("/") && !value.endsWith(".")
+    && value.split("/").every(part => !part.startsWith(".") && !part.endsWith(".lock"));
+}
+
+function literalPath(value: string): boolean {
+  if (!value || value.length > 512 || value.startsWith("-") || !/^[A-Za-z0-9_./-]+$/.test(value)) return false;
+  const relative = value.startsWith("./") ? value.slice(2) : value;
+  return !relative.startsWith("-") && relative.split("/").every(part => !!part && part !== "." && part !== ".."
+    && ![".git", ".agenthub"].includes(part.toLowerCase()));
+}
+
+const data = (value: string | undefined, limit: number): value is string =>
+  typeof value === "string" && value.length <= limit && !!value.trim() && !/[\p{Cc}\p{Cf}]/u.test(value);
+
+export function taskShellBindingValid(binding: TaskShellBinding): boolean {
+  return !!binding && shortBranch(binding.branch) && shortBranch(binding.defaultBranch)
+    && ![binding.defaultBranch.toLowerCase(), "main", "master"].includes(binding.branch.toLowerCase());
+}
+
+/**
+ * Lexical data only: this does not authorize execution, bind a task, resolve a program or read Git/files.
+ * The caller supplies authoritative native cwd/environment, current child/task/worktree/branch evidence and
+ * action/privacy policy, then guards every returned path and executable before answering the native prompt.
+ * Quoted punctuation is data only in commit messages and PR title/body values; path/ref operands stay plain.
+ */
+export function taskShellCommand(command: unknown, binding: TaskShellBinding): TaskShellCommand | undefined {
+  if (!taskShellBindingValid(binding)) return undefined;
+  const parsed = parseSimpleShell(command);
+  if (!parsed) return undefined;
+  const argv = parsed.words;
+  const result = (kind: TaskShellCommand["kind"], program: TaskShellCommand["program"], paths: readonly string[] = []): TaskShellCommand =>
+    ({ kind, program, argv: [...argv], paths: [...paths] });
+  if (argv.length === 2 && argv[0] === "scripts/check.sh" && argv[1] === "--changed") return result("check", "scripts/check.sh", ["scripts/check.sh"]);
+  if (argv[0] === "bun") {
+    if (argv.length === 3 && argv[1] === "run" && argv[2] === "build") return result("build", "bun");
+    const paths = argv.slice(2);
+    if (argv[1] === "test" && paths.length >= 1 && paths.length <= 16 && paths.every(path => {
+      const relative = path.startsWith("./") ? path.slice(2) : path;
+      return literalPath(path) && relative.startsWith("test/") && /^[A-Za-z0-9_][A-Za-z0-9_.-]*\.test\.ts$/.test(relative.split("/").at(-1)!);
+    })) return result("test", "bun", paths);
+    return undefined;
+  }
+  if (argv[0] === "git") {
+    if (argv[1] === "add") {
+      const paths = argv.slice(argv[2] === "--" ? 3 : 2);
+      if (paths.length >= 1 && paths.length <= 64 && paths.every(literalPath)) return result("add", "git", paths);
+    }
+    if (argv.length === 4 && argv[1] === "commit" && argv[2] === "-m" && data(argv[3], 1000)) return result("commit", "git");
+    if (argv[1] === "push" && (argv.length === 4 && argv[2] === "origin" && argv[3] === binding.branch
+      || argv.length === 5 && argv[2] === "-u" && argv[3] === "origin" && argv[4] === binding.branch)) return result("push", "git");
+    return undefined;
+  }
+  if (argv[0] !== "gh" || argv[1] !== "pr") return undefined;
+  if (argv.length === 4 && argv[3] === binding.branch) {
+    if (argv[2] === "view") return result("pr-view", "gh");
+    if (argv[2] === "checks") return result("pr-checks", "gh");
+  }
+  if (argv[2] !== "create" || argv.length !== 11) return undefined;
+  const allowed = new Set(["--base", "--head", "--title", "--body", "--body-file"]), flags = new Map<string, string>();
+  for (let index = 3; index < argv.length; index += 2) {
+    const flag = argv[index]!, value = argv[index + 1];
+    if (!allowed.has(flag) || value === undefined || flags.has(flag)) return undefined;
+    flags.set(flag, value);
+  }
+  if (flags.get("--base") !== binding.defaultBranch || flags.get("--head") !== binding.branch || !data(flags.get("--title"), 1000)) return undefined;
+  if (flags.has("--body") === flags.has("--body-file")) return undefined;
+  if (flags.has("--body")) return data(flags.get("--body"), 3000) ? result("pr-create", "gh") : undefined;
+  const file = flags.get("--body-file")!;
+  return literalPath(file) ? result("pr-create", "gh", [file]) : undefined;
+}

package/src/hub/task-shell-default.ts

@@ -0,0 +1,78 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { chmodSync, lstatSync, mkdtempSync, rmSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { stopOwnedProcess, trackGroup } from "./child-process.ts";
+import { hostExecutable } from "./host-executable.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
+import { realPath } from "./project.ts";
+import { isGitHubRepository } from "./spec-read.ts";
+import { shortBranch } from "./task-shell-command.ts";
+
+const OUTPUT_LIMIT = 64 * 1024;
+function remoteHead(bytes: Buffer): string | undefined {
+  const output = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  if (!output.endsWith("\n")) return;
+  const lines = output.slice(0, -1).split("\n");
+  if (lines.length !== 2) return;
+  const symbolic = lines.filter(line => /^ref: refs\/heads\/.+\tHEAD$/.test(line));
+  const oid = lines.filter(line => /^[0-9a-f]{40}\tHEAD$/.test(line));
+  if (symbolic.length !== 1 || oid.length !== 1) return;
+  const branch = symbolic[0]!.slice("ref: refs/heads/".length, -"\tHEAD".length);
+  return shortBranch(branch) ? branch : undefined;
+}
+
+/** Startup authority comes from the fixed GitHub remote, never a mutable local origin/HEAD or repository config.
+ * No task/native environment or account credentials are inherited. Unknown remote evidence keeps automatic execution unavailable. */
+export async function readTaskShellDefaultBranch(root: string, env: Record<string, string>, current: () => boolean, projectRoot: string, repository?: string, timeoutMs = 5000): Promise<string | undefined> {
+  let temporary: string | undefined, proc: ChildProcess | undefined;
+  try {
+    if (!isGitHubRepository(repository) || !current() || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000
+      || !env.PATH || env.PATH.length > 16384 || env.PATH.split(":").some(dir => !isAbsolute(dir) || dir.split("/").includes(".."))) return;
+    root = realPath(root);
+    const project = realPath(projectRoot), executable = hostExecutable("git", root, env.PATH), rel = relative(project, executable);
+    if (!rel || rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel) || !lstatSync(executable).isFile()) return;
+    temporary = realPath(mkdtempSync(join(realPath("/tmp"), "ahub-default-"))); chmodSync(temporary, 0o700);
+    const own = temporary, stat = lstatSync(own), identity = JSON.stringify([stat.dev, stat.ino, stat.mode]);
+    const remove = () => {
+      const held = lstatSync(own);
+      if (!held.isDirectory() || realPath(own) !== own || JSON.stringify([held.dev, held.ino, held.mode]) !== identity) throw new Error("unavailable");
+      rmSync(own, { recursive: true, force: true }); temporary = undefined;
+    };
+    const environment = hubGitEnv({ PATH: env.PATH, HOME: own, XDG_CONFIG_HOME: own, LANG: env.LANG ?? "C", TERM: "dumb", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CEILING_DIRECTORIES: own }, { repositoryIsolation: true });
+    const argv = hubGitArgv(["-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "ls-remote", "--symref", "--exit-code", `https://github.com/${repository}.git`, "HEAD"]);
+    if (!current()) { remove(); return; }
+    return await new Promise<string | undefined>(resolve => {
+      let done = false, bytes = 0, overflowed = false;
+      const output: Buffer[] = [];
+      let timer: ReturnType<typeof setTimeout> | undefined, watcher: ReturnType<typeof setInterval> | undefined;
+      const finish = async (code: number | null) => {
+        if (done) return; done = true; clearTimeout(timer); clearInterval(watcher);
+        // Do not remove a private cwd/HOME while an owned group may still use it. The existing helper refuses unknown ownership.
+        try { if (proc) await stopOwnedProcess(proc, { group: true }); remove(); }
+        catch { resolve(undefined); return; }
+        try { resolve(code === 0 && !overflowed && current() ? remoteHead(Buffer.concat(output)) : undefined); }
+        catch { resolve(undefined); }
+      };
+      try { proc = spawn(executable, argv.slice(1), { cwd: own, env: environment, detached: true, stdio: ["ignore", "pipe", "pipe"] }); }
+      catch { void finish(null); return; }
+      timer = setTimeout(() => void finish(null), timeoutMs);
+      watcher = setInterval(() => { try { if (!current()) void finish(null); } catch { void finish(null); } }, 50); watcher.unref();
+      proc.once("spawn", () => trackGroup(proc!));
+      const take = (chunk: Buffer, stdout: boolean) => {
+        if (done) return;
+        bytes += chunk.length;
+        if (bytes > OUTPUT_LIMIT) { overflowed = true; void finish(null); return; }
+        if (stdout) output.push(Buffer.from(chunk));
+      };
+      proc.stdout!.on("data", (chunk: Buffer) => take(chunk, true));
+      proc.stderr!.on("data", (chunk: Buffer) => take(chunk, false));
+      proc.once("error", () => void finish(null));
+      proc.once("exit", code => { if (code !== 0) void finish(null); });
+      proc.once("close", code => void finish(code));
+    });
+  } catch {
+    // A spawn/setup failure owns no live group; otherwise only confirmed stop above permits removing the private directory.
+    if (!proc && temporary) { try { rmSync(temporary, { recursive: true, force: true }); } catch { /* unknown cleanup remains private */ } }
+    return undefined;
+  }
+}

package/src/hub/task-shell-proof.ts

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { accessSync, closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { guardPath } from "../local/tools.ts";
+import { hostExecutable } from "./host-executable.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
+import { grantablePath } from "./permission-mode.ts";
+import { realPath } from "./project.ts";
+import { taskShellBindingValid, taskShellCommand, type TaskShellBinding, type TaskShellCommand } from "./task-shell-command.ts";
+
+const within = (root: string, path: string) => { const rel = relative(root, path); return !rel || rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel); };
+const stamp = (path: string) => { const s = lstatSync(path, { throwIfNoEntry: false }); return s ? [path, s.dev, s.ino, s.mode, s.size, s.mtimeMs, s.ctimeMs] : [path, "missing"]; };
+
+/** One bounded synchronous metadata read. No network, ambient repository selectors or repository helper execution.
+ * ponytail: each reader's synchronous Git burst can block the hub for up to 1.5 seconds; move to asynchronous reads with one shared proof budget. */
+function gitReader(root: string, env: Record<string, string>, current: () => boolean, projectRoot = root) {
+  if (!env.PATH || env.PATH.length > 16384 || env.PATH.split(":").some(dir => !isAbsolute(dir) || dir.split("/").includes(".."))) throw new Error("unavailable");
+  const executable = hostExecutable("git", root, env.PATH), deadline = performance.now() + 1500;
+  if (within(realPath(projectRoot), executable)) throw new Error("unavailable");
+  return (args: string[], absent = false): string => {
+    const left = Math.floor(deadline - performance.now());
+    if (!current() || left <= 0) throw new Error("unavailable");
+    const result = spawnSync(executable, hubGitArgv(["-C", root, ...args]).slice(1), {
+      cwd: root, env: hubGitEnv(env, { repositoryIsolation: true }), encoding: "utf8", timeout: left, maxBuffer: 64 * 1024,
+    });
+    if (!current() || result.error || result.status !== 0 && !(absent && result.status === 1)) throw new Error("unavailable");
+    return result.stdout;
+  };
+}
+
+export { readTaskShellDefaultBranch } from "./task-shell-default.ts";
+
+/** Attached HEAD is live evidence; the default branch must be pinned by the host before task execution. */
+export function readTaskShellBinding(root: string, env: Record<string, string>, current: () => boolean, projectRoot = root, defaultBranch?: string): TaskShellBinding | undefined {
+  try {
+    if (!defaultBranch) return;
+    const git = gitReader(realPath(root), env, current, projectRoot);
+    if (realPath(git(["rev-parse", "--show-toplevel"]).replace(/\n$/, "")) !== realPath(root)) return;
+    const branch = git(["symbolic-ref", "--quiet", "--short", "HEAD"]).replace(/\n$/, "");
+    const binding = { branch, defaultBranch };
+    return taskShellBindingValid(binding) && current() ? binding : undefined;
+  } catch { return undefined; }
+}
+
+export interface TaskShellProofOptions {
+  root: string; projectRoot: string; deny: string[]; readOnly?: string[]; protectInstructions: boolean;
+  binding: TaskShellBinding; env: Record<string, string>; repository?: string;
+  /** Host privacy screen for the captured PR body. Missing or unknown screening never grants a body-file upload. */
+  publicText?: (text: string) => boolean;
+}
+export interface TaskShellProof {
+  fingerprint: string; program: TaskShellCommand["program"]; executable: string; argv: readonly string[];
+  env: Readonly<Record<string, string>>; requiresSandbox: boolean;
+}
+
+/** Capture only a bounded regular file; the privileged CLI receives these screened bytes, never a path it can reopen later. */
+function bodyFileText(file: string): string {
+  const initial = lstatSync(file);
+  if (!initial.isFile() || initial.size > 12000) throw new Error("unavailable");
+  const before = stamp(file), fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > 12000 || JSON.stringify(before) !== JSON.stringify([file, stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs])) throw new Error("unavailable");
+    const bytes = Buffer.alloc(12001), count = readSync(fd, bytes, 0, bytes.length, 0), after = fstatSync(fd);
+    if (count !== stat.size || JSON.stringify(stamp(file)) !== JSON.stringify(before)
+      || [after.dev, after.ino, after.mode, after.size, after.mtimeMs, after.ctimeMs].some((value, index) => value !== [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs][index])) throw new Error("unavailable");
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, count));
+    if (!text.trim() || text.length > 3000 || text.includes("\0")) throw new Error("unavailable");
+    return text;
+  } finally { closeSync(fd); }
+}
+
+/** Reuse the core's command-line hardening as environment config for Git children spawned internally by gh. */
+function gitChildEnvironment(env: Record<string, string>): Record<string, string> {
+  const result = Object.fromEntries(Object.entries(hubGitEnv(env, { repositoryIsolation: true })).filter((entry): entry is [string, string] => typeof entry[1] === "string"));
+  const argv = hubGitArgv([]).slice(1), configs: string[] = [];
+  for (let index = 0; index < argv.length; index++) {
+    if (argv[index] === "--no-pager") continue;
+    if (argv[index] !== "-c" || !argv[index + 1]?.includes("=")) throw new Error("unavailable");
+    configs.push(argv[++index]!);
+  }
+  result.GIT_CONFIG_COUNT = String(configs.length);
+  configs.forEach((config, index) => {
+    const split = config.indexOf("=");
+    result[`GIT_CONFIG_KEY_${index}`] = config.slice(0, split);
+    result[`GIT_CONFIG_VALUE_${index}`] = config.slice(split + 1);
+  });
+  return result;
+}
+
+/** Host task-command proof only; read-only commands continue to use the existing #816 proof. */
+export function proveTaskShell(command: unknown, options: TaskShellProofOptions, current: () => boolean): TaskShellProof | undefined {
+  try {
+    if (!current() || options.readOnly?.length) return;
+    const form = taskShellCommand(command, options.binding);
+    if (!form) return;
+    const root = realPath(options.root), project = realPath(options.projectRoot), env = options.env;
+    if (!env.PATH || env.PATH.length > 16384 || env.PATH.split(":").some(dir => !isAbsolute(dir) || dir.split("/").includes(".."))) return;
+    const binding = readTaskShellBinding(root, env, current, project, options.binding.defaultBranch);
+    if (!binding || binding.branch !== options.binding.branch || binding.defaultBranch !== options.binding.defaultBranch) return;
+    const paths = new Set<string>();
+    const path = (value: string, writing = false) => {
+      const target = guardPath({ cwd: root, deny: options.deny, readOnly: options.readOnly }, value, "read");
+      if (writing && !grantablePath(root, target, value, options.protectInstructions)) throw new Error("unavailable");
+      paths.add(resolve(root, value)); paths.add(target); return target;
+    };
+    for (const value of form.paths) path(value, form.kind === "add");
+    const executable = form.program === "scripts/check.sh" ? path("scripts/check.sh") : hostExecutable(form.program, root, env.PATH);
+    if (form.program !== "scripts/check.sh" && within(project, executable)) return;
+    accessSync(executable, constants.X_OK);
+    if (!lstatSync(executable).isFile()) return;
+    paths.add(executable);
+    let argv = [...form.argv.slice(1)], repository: string | undefined;
+    let effectiveEnv: Record<string, string> = { ...env };
+    let bodyFileIndex = -1;
+    if (form.kind === "pr-create") for (let index = 3; index < form.argv.length; index += 2) {
+      if (form.argv[index] === "--body-file") bodyFileIndex = index - 1; // Effective argv excludes the program.
+    }
+    if (bodyFileIndex >= 0) {
+      if (!options.publicText) return;
+      const body = bodyFileText(path(argv[bodyFileIndex + 1]!));
+      if (options.publicText(body) !== true) return;
+      argv.splice(bodyFileIndex, 2, "--body", body);
+    }
+    if (form.program === "git" || form.program === "gh") {
+      const git = gitReader(root, env, current, project);
+      // Includes can change config between proof and execution; partial clones can trigger implicit helper/network activity.
+      if (git(["config", "--get-regexp", "^(include\\.path|includeif\\..*\\.path|extensions\\.partialclone|remote\\..*\\.promisor)$"], true).trim()) return;
+      // Only add/commit can run attribute-selected clean/smudge or content-diff drivers. Push/gh must keep working with a global LFS install.
+      if ((form.kind === "add" || form.kind === "commit") && git(["config", "--get-regexp", "^(filter\\..*\\.(clean|smudge|process)|diff\\..*\\.(command|textconv))$"], true).trim()) return;
+      if (form.kind === "add") {
+        const selected = git(["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...form.paths]).split("\0").filter(Boolean);
+        if (selected.length > 256) return;
+        for (const value of selected) path(value, true);
+      }
+      if (form.kind === "commit") {
+        const staged = git(["diff", "--no-ext-diff", "--no-textconv", "--cached", "--name-only", "-z"]).split("\0").filter(Boolean);
+        if (staged.length > 256) return;
+        for (const value of staged) path(value, true);
+      }
+      if (form.kind === "push" || form.program === "gh") {
+        const expected = options.repository?.toLowerCase();
+        if (!expected || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(expected)) return;
+        const urls = [...git(["remote", "get-url", "--push", "--all", "origin"]).trim().split("\n"), ...git(["remote", "get-url", "--all", "origin"]).trim().split("\n")];
+        if (!urls.length || urls.length > 16 || urls.some(url => {
+          const match = /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?\/?$/.exec(url);
+          return match?.[1]?.toLowerCase() !== expected;
+        })) return;
+        // No remote-selected helper or implicit extra push effect is part of the closed command shape.
+        if (git(["config", "--get-regexp", "^(core\\.(sshcommand|gitproxy)|remote\\.origin\\.(vcs|proxy|receivepack|push|mirror)|push\\.pushoption)$"], true).trim()) return;
+        repository = expected;
+      }
+      if (form.kind === "push") argv[argv.length - 1] = `refs/heads/${binding.branch}:refs/heads/${binding.branch}`;
+      if (form.program === "git") {
+        effectiveEnv = Object.fromEntries(Object.entries(hubGitEnv(env, { repositoryIsolation: true })).filter((entry): entry is [string, string] => typeof entry[1] === "string"));
+        argv = hubGitArgv([
+          "-c", "commit.gpgSign=false", "-c", "push.gpgSign=false", "-c", "gc.auto=0", "-c", "maintenance.auto=false",
+          ...(form.kind === "push" ? ["-c", "push.followTags=false", "-c", "remote.origin.mirror=false", "-c", "push.recurseSubmodules=no"] : []), ...argv,
+        ]).slice(1);
+      } else {
+        effectiveEnv = gitChildEnvironment(env);
+        argv.push("--repo", `https://github.com/${repository}`);
+      }
+    }
+    const requiresSandbox = form.kind === "check" || form.program === "bun";
+    const rootStat = lstatSync(root);
+    const fingerprint = createHash("sha256").update(JSON.stringify([root, rootStat.dev, rootStat.ino, binding, effectiveEnv, executable, argv, repository, requiresSandbox, [...paths].map(stamp)])).digest("hex");
+    return current() ? { fingerprint, program: form.program, executable, argv: Object.freeze(argv), env: Object.freeze(effectiveEnv), requiresSandbox } : undefined;
+  } catch { return undefined; }
+}

package/src/hub/task-shell-sandbox.ts

@@ -0,0 +1,61 @@
+import { accessSync, constants, lstatSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { sbplString } from "../local/deny.ts";
+import { hostExecutable } from "./host-executable.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
+import { realPath } from "./project.ts";
+import { taskShellBindingValid } from "./task-shell-command.ts";
+
+export interface TaskShellSandboxOptions { projectRoot: string; env: Record<string, string> }
+const inside = (root: string, file: string) => { const rel = relative(root, file); return !rel || rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel); };
+const literal = (file: string) => `(literal ${sbplString(file)})`;
+const subpath = (file: string) => `(subpath ${sbplString(file)})`;
+
+/** Deny-only refinement of the worker profile, never an execution grant or a replacement sandbox.
+ * All Git metadata is immutable here, including objects: object content is later trusted by privileged Git operations.
+ * Unknown layouts (including a non-linked checkout) ask instead of guessing metadata boundaries.
+ * ponytail: synchronous Git evidence shares a 1.5 second burst; an async host proof is the upgrade path. */
+export function taskShellSandboxRestrictions(root: string, branch: string, options: TaskShellSandboxOptions): string | undefined {
+  try {
+    if (!taskShellBindingValid({ branch, defaultBranch: "main" }) || !options.env.PATH || options.env.PATH.length > 16384
+      || options.env.PATH.split(":").some(dir => !isAbsolute(dir) || dir.split("/").includes(".."))) return;
+    root = realPath(root);
+    const project = realPath(options.projectRoot), executable = hostExecutable("git", root, options.env.PATH);
+    if (inside(project, executable) || !lstatSync(executable).isFile()) return;
+    accessSync(executable, constants.X_OK);
+    const deadline = performance.now() + 1500;
+    const git = (...args: string[]) => {
+      const timeout = Math.floor(deadline - performance.now()); if (timeout <= 0) throw new Error("unavailable");
+      const result = spawnSync(executable, hubGitArgv(["-C", root, ...args]).slice(1), {
+        cwd: root, env: hubGitEnv(options.env, { repositoryIsolation: true }), encoding: "utf8", timeout, maxBuffer: 16384,
+      });
+      if (result.error || result.status !== 0 || !/^[^\r\n]+\n$/.test(result.stdout)) throw new Error("unavailable");
+      return result.stdout.slice(0, -1);
+    };
+    if (git("symbolic-ref", "--quiet", "--short", "HEAD") !== branch || realPath(git("rev-parse", "--show-toplevel")) !== root) return;
+    const gitDir = realPath(git("rev-parse", "--absolute-git-dir"));
+    const commonDir = realPath(resolve(root, git("rev-parse", "--git-common-dir")));
+    // Only a proven linked-worktree layout is supported; this refinement grants no metadata writes, even to the current worktree.
+    const worktreePart = relative(commonDir, gitDir).split("/");
+    if (worktreePart.length !== 2 || worktreePart[0] !== "worktrees" || !worktreePart[1] || gitDir === commonDir) return;
+    const entries = new Set<string>();
+    const directory = (file: string) => {
+      if (!lstatSync(file).isDirectory() || realPath(file) !== file || Buffer.byteLength(file) > 900 || /[\p{Cc}\p{Cf}]/u.test(file)) throw new Error("unavailable");
+      entries.add(file);
+    };
+    for (const metadata of [commonDir, gitDir]) directory(metadata);
+    for (let parent = dirname(gitDir); inside(commonDir, parent); parent = dirname(parent)) {
+      directory(parent); if (parent === commonDir) break;
+    }
+    // Protect metadata ancestors too when the metadata sits beneath the writable execution root.
+    for (const metadata of [commonDir, gitDir]) for (let parent = dirname(metadata); inside(root, parent); parent = dirname(parent)) {
+      directory(parent); if (parent === root) break;
+    }
+    return [
+      `(deny file-write* ${subpath(commonDir)} ${subpath(gitDir)})`,
+      // Exact metadata ancestor entries cannot be renamed or replaced either.
+      `(deny file-write* ${[...entries].sort().map(literal).join(" ")})`,
+    ].join("\n");
+  } catch { return undefined; }
+}