@staix/agent-hub 0.18.0 → 0.20.0

package/src/hub/host-executable.ts

@@ -1,12 +1,31 @@
 import type { ReadOnlyProgram } from "./read-only-shell.ts";
 import { isAbsolute, relative } from "node:path";
+import { lstatSync } from "node:fs";
 import { realPath } from "./project.ts";
 
 /** A repo-writable PATH shim is not a host-owned authenticated capability. No caller-selected binary. */
-export function hostExecutable(name: "gh" | "container" | "git" | "dot" | "ssh" | "tar" | ReadOnlyProgram, projectDir: string, path = process.env.PATH ?? ""): string {
+export function hostExecutable(name: "gh" | "bun" | "container" | "git" | "dot" | "ssh" | "tar" | ReadOnlyProgram, projectDir: string, path = process.env.PATH ?? ""): string {
   const found = Bun.which(name, { PATH: path });
   if (!found || !isAbsolute(found)) throw new Error(`${name} unavailable`);
   const target = realPath(found), inside = relative(realPath(projectDir), target);
   if (!inside || inside !== ".." && !inside.startsWith("../") && !isAbsolute(inside)) throw new Error(`${name} unavailable`);
   return target;
 }
+
+/** A privileged command's children must not discover a project-controlled PATH shim either. */
+export function hostShellPath(projectDir: string, executionDir: string, value = process.env.PATH ?? "/usr/bin:/bin"): string | undefined {
+  try {
+    if (!value || value.length > 16384 || value.split(":").length > 128) return;
+    const roots = [realPath(projectDir), realPath(executionDir)], directories = new Set<string>();
+    const inside = (path: string) => roots.some(root => { const p = relative(root, path); return !p || p !== ".." && !p.startsWith("../") && !isAbsolute(p); });
+    for (const entry of value.split(":")) {
+      if (!isAbsolute(entry) || entry.split("/").includes("..")) return;
+      if (inside(entry)) continue;
+      try {
+        const canonical = realPath(entry);
+        if (!inside(canonical) && lstatSync(canonical).isDirectory()) directories.add(canonical);
+      } catch { /* A missing PATH directory supplies no trusted program. */ }
+    }
+    return directories.size ? [...directories].join(":") : undefined;
+  } catch { return undefined; }
+}

package/src/hub/instances.ts

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { canonicalPath, realPath } from "./project.ts";
 import { defaultPeerRoles, definitionOf, type AdapterDefinition, type StartForm, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { isPermissionMode, type PermissionMode } from "./permission-mode.ts";
+import { isReviewScope } from "./review-scope.ts";
 
 export interface InstanceConfig {
   kind: string;
@@ -11,9 +12,11 @@ export interface InstanceConfig {
   start_mode?: StartForm;
   permission_mode?: PermissionMode;
   review_mode?: "fresh";
+  /** A fresh reviewer's review scope (#852): `code` reads the code only, `full` also runs tests and reads CI. Machine-local, tier 3. */
+  review_scope?: "full" | "code";
   worktree?: string;
   readOnly?: boolean;
-  /** Jcode instances only (#685): their own native data home, and optional model selection. Machine-local, never editable from settings. */
+  /** Jcode instances (#685): their own native data home, and optional model selection. A headless Claude implementer also takes `model` (#844). Machine-local, never editable from settings. */
   jcode_home?: string;
   provider?: string;
   model?: string;
@@ -129,7 +132,9 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
     const path = `instances.${id}`, entry = fields(descriptor.value, path);
     const declaredKind: unknown = entry.kind?.value;
     const jcodeFields = typeof declaredKind === "string" && resolve(declaredKind)?.instances?.nativeHome === true;
-    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly", ...(jcodeFields ? JCODE_FIELDS : [])].includes(key))) return fail(path, "unsupported field");
+    // #844: a kind whose headless variant declares `instances.modelSelect` may name its model; no other kind but Jcode has the field.
+    const modelSelect = typeof declaredKind === "string" && resolve(declaredKind)?.headlessVariant?.instances?.modelSelect === true;
+    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly", "review_scope", ...(jcodeFields ? JCODE_FIELDS : []), ...(modelSelect ? ["model"] : [])].includes(key))) return fail(path, "unsupported field");
     const kind: unknown = entry.kind?.value;
     if (typeof kind !== "string") return fail(`${path}.kind`, "must name a native kind");
     const definition = resolve(kind), prefix = `${kind}-`;
@@ -185,6 +190,17 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
       if (++jcodeCount > MAX_JCODE_INSTANCES) return fail("instances", `at most ${MAX_JCODE_INSTANCES} extra Jcode instances are supported per project`);
       Object.assign(value, jcodeInstanceFields(entry, path));
     }
+    if (entry.model && modelSelect) {
+      if (!headlessWriter) return fail(`${path}.model`, "only a headless implementer takes a model");
+      const word: unknown = entry.model.value;
+      if (typeof word !== "string" || !NATIVE_WORD.test(word)) return fail(`${path}.model`, "must be one bounded printable word without spaces");
+      value.model = word;
+    }
+    if (entry.review_scope) {
+      if (!freshReviewer) return fail(`${path}.review_scope`, "only a fresh reviewer instance has a review scope");
+      if (!isReviewScope(entry.review_scope.value)) return fail(`${path}.review_scope`, 'must be "code" or "full"');
+      value.review_scope = entry.review_scope.value;
+    }
     if (entry.readOnly) value.readOnly = entry.readOnly.value as boolean;
     if (entry.roles) { value.roles = roles(entry.roles.value, `${path}.roles`); Object.freeze(value.roles); }
     if (entry.start_mode) {

package/src/hub/lifecycle.ts

@@ -119,7 +119,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
         try {
           daemon = await startDaemon({ cwd: project.root, stateDir: project.stateDir, projectId: project.id, instanceId,
             controlPort: base + CONTROL, codexAppPort: base + CODEX_APP, codexProxyPort: base + CODEX_PROXY,
-            unattended, onShutdownStart,
+            unattended, onShutdownStart, agentDrift: true,
             // #269: the real terminal providers belong to the running product; a daemon built without them opens nothing.
             terminal: (template) => terminalOpener({ template, cwd: project.root, stateDir: project.stateDir }) });
           break;

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/peers.ts

@@ -1,5 +1,6 @@
 import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
 import type { PermissionMode } from "./permission-mode.ts";
+import type { StartForm } from "../adapters/registry-types.ts";
 
 export interface DeliveryReceipt {
   id: string;
@@ -14,6 +15,15 @@ export interface OwnedToolsLaunch {
   launchId: string; generation: string; sessionId: string; signal: AbortSignal; task?: number; permissionHook: true;
 }
 
+export interface FrontendProxyPort {
+  readonly url: string;
+  readonly attached: boolean;
+  /** Only before a frontend attaches, while offline and with no native restoration debt. */
+  setStartupPermissionMode(mode: PermissionMode): void;
+  /** Clear to ask while retaining any native restoration debt; false means its baseline is unknown. */
+  clearPermissionMode(): boolean;
+}
+
 export interface PeerAdapter {
   readonly id: PeerId;
   ownedTools?(launchId: unknown): OwnedToolsLaunch | undefined;
@@ -27,6 +37,30 @@ export interface PeerAdapter {
   readonly permissionModeState?: PermissionMode | "unknown" | "unmanaged";
   /** Resolve only after native acknowledgement. This changes approval frequency, never the sandbox. */
   setPermissionMode?(mode: PermissionMode): Promise<void>;
+  /** Never offered delivery retry; absent/false permits retry, present undefined refuses it. */
+  readonly deliveryOnly?: boolean;
+  /** The hub owns this runtime and may stop it; absent or undefined refuses. */
+  readonly hubOwned?: boolean;
+  /** An owned process remains whose exit is unconfirmed. */
+  readonly pendingOwnedProcess?: boolean;
+  /** Native running form; absent keeps the site's default, present undefined is unknown. */
+  readonly form?: StartForm;
+  /** Absent is settled; false or a present undefined value refuses recovery readiness. */
+  readonly recoveryReady?: boolean;
+  /** Capture live resume evidence before a requested stop; throws when unavailable. */
+  captureResume?(): Promise<Record<string, unknown>>;
+  /** Native session binding; absence or undefined is unbound, never inferred from a different reader. */
+  readonly nativeSession?: string;
+  /** Fixed-builtin native proof only; present undefined is unknown, not an absent proxy. */
+  readonly frontendProxy?: FrontendProxyPort;
+  /** Fixed operator notices from builtin native adapters, never provider text or native ids. */
+  readonly statusNotice?: { code: "unidentified-cancellation" | "qwen-detached" | "qwen-stalled"; message: string };
+  /** Fixed builtins with session.nativeRevert only. Native conversation effects remain in the adapter. */
+  revertTurn?(nativeTurn: string): Promise<void>;
+  /** Leave the roster without stopping a person's terminal. */
+  detachForRoster?(resetMode: PermissionMode): void | Promise<void>;
+  /** Return to the roster after detachForRoster. */
+  resumeFromRoster?(): Promise<void>;
   /** A peer the hub drives itself (Pi, the local worker). It cannot be trusted to rate its own urgency: the bus caps it. */
   readonly hubNative?: boolean;
   /** Never handed a delivery: its queue waits for `Bus.pull` (a Claude session that cannot show channel pushes, issue #205). */

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/settings.ts

@@ -57,6 +57,7 @@ export const SETTINGS: readonly SettingDef[] = [
   ...["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "number", min: 1, max: 2_147_483_647 / (key === "interval_s" ? 1000 : 60_000), store: "config", applies: "live", risk: "raises", path: ["task_sweep", key] })),
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "live", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
   { key: "tasks.escalate_after", group: "Routing", label: "Escalate after N consecutive changes_requested", type: "integer", min: 1, max: 10, store: "config", applies: "live", risk: "raises", path: ["tasks", "escalate_after"] },
+  { key: "tasks.auto_pull", group: "Switches", label: "Auto-pull the top reserved ready card when a planner slot frees", type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["tasks", "auto_pull"] },
   { key: "planner", group: "Roles", label: "Planners (task-local selection)", type: "peers", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },

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,79 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { chmodSync, lstatSync, mkdtempSync, rmSync } from "node:fs";
+import { dirname, 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;
+    };
+    // Git stops before inspecting a ceiling ancestor; naming cwd itself still permits discovery in its parent.
+    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: dirname(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;
+  }
+}