@staix/agent-hub 0.17.0 → 0.19.0

package/src/hub/sdlc.ts

@@ -33,7 +33,12 @@ export type StageGate = "issue" | "pr" | "local" | "review" | "checks" | "criter
 export interface StageDefinition { base: SdlcBaseStage; actor: string; entry_gates: StageGate[]; exit_gates: StageGate[]; after: string[]; }
 export type SdlcMode = "off" | "advise" | "enforce";
 /** `workflow: "gsd-lite"` marks the retired setting during its window (#481 S8): every task then needs a criteria checklist. */
-export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+/** #786: `off` never merges, `dry-run` reports the decision and runs nothing, `on` runs the guarded `gh pr merge`. */
+export type AutoMergeMode = "off" | "dry-run" | "on";
+export const AUTO_MERGE_MODES: readonly AutoMergeMode[] = ["off", "dry-run", "on"];
+/** #786: one repository's own gate: its required checks (before the top-level list) and its own merge mode. */
+export interface RepoMergePolicy { requiredChecks?: string[]; autoMerge?: AutoMergeMode }
+export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; mode: SdlcMode; requiredChecks: string[]; /** #786: absent reads as "off"; written only when the file names it. */ autoMerge?: AutoMergeMode; /** #786: per-repository tables, keyed by lowercase owner/name. */ repos?: Record<string, RepoMergePolicy>; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
 export interface PlanReviewReceipt {
   planner: string;
   planAuthor?: string | null;
@@ -43,7 +48,17 @@ export interface PlanReviewReceipt {
   scope?: CostPlan;
   issue?: PlanIssueMetadata;
 }
+/** Host-observed guarded merge evidence. Never accepted from a tool or restored across an artifact relink. */
+export interface MergeRecord {
+  repo: string; pr: number; head: string; at: number;
+  state: "merged" | "not_merged" | "unknown";
+  exit: number; mergeCommit?: string;
+  cleanup: "not_started" | "claimed" | "deleted" | "already_gone" | "skipped" | "unknown";
+  reason?: "not_merged" | "missing_commit" | "metadata_unknown" | "identity_changed" | "protected_branch" | "default_branch" | "head_changed" | "authority_changed" | "delete_unconfirmed";
+  ownerNotice: "not_started" | "claimed" | "sent" | "unknown";
+}
 export interface SdlcReceipt {
+  merge?: MergeRecord;
   stage: SdlcStage;
   planReview?: PlanReviewReceipt;
   criteria?: CriteriaReceipt;
@@ -78,6 +93,8 @@ export interface PrEvidence {
   base?: string;
   baseHead?: string;
   mergeCommit?: string;
+  /** #786: the PR's head branch name, read so a release branch is refused; never used as an identity. */
+  headBranch?: string;
 }
 const sha = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
 const repo = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
@@ -131,12 +148,37 @@ function definitions(raw: unknown, stages: unknown, phaseAlias: { allowed: boole
   return { stages: [...stages], definitions: result };
 }
 
+const checkList = (value: unknown, what: string): string[] => {
+  if (!Array.isArray(value) || value.length > 32 || value.some(c => typeof c !== "string" || !c.trim() || c.length > 120 || /[\r\n\x00-\x1f]/.test(c)) || new Set(value).size !== value.length) throw new Error(`${what}: expected at most 32 unique nonempty names`);
+  return [...value] as string[];
+};
+const autoMergeMode = (value: unknown, what: string): AutoMergeMode => {
+  if (!AUTO_MERGE_MODES.includes(value as AutoMergeMode)) throw new Error(`${what}: expected off, dry-run or on`);
+  return value as AutoMergeMode;
+};
+/** #786: `[repos."owner/name"]` tables. Unknown keys are refused like everywhere else in this file. */
+function mergeRepos(value: unknown): Record<string, RepoMergePolicy> | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length > 16) throw new Error("sdlc.repos: expected at most 16 tables named owner/repository");
+  const result: Record<string, RepoMergePolicy> = Object.create(null);
+  for (const [name, table] of Object.entries(value)) {
+    if (!repo(name)) throw new Error(`sdlc.repos: "${String(name).slice(0, 60)}" is not an owner/repository name`);
+    if (!table || typeof table !== "object" || Array.isArray(table)) throw new Error(`sdlc.repos.${name}: expected a table`);
+    const row = table as Record<string, unknown>;
+    for (const key of Object.keys(row)) if (!["required_checks", "auto_merge"].includes(key)) throw new Error(`sdlc.repos.${name}.${key}: unknown field`);
+    const key = name.toLowerCase();
+    if (result[key]) throw new Error(`sdlc.repos.${name}: repeats another table (names are case-insensitive)`);
+    result[key] = { ...(row.required_checks === undefined ? {} : { requiredChecks: checkList(row.required_checks, `sdlc.repos.${name}.required_checks`) }), ...(row.auto_merge === undefined ? {} : { autoMerge: autoMergeMode(row.auto_merge, `sdlc.repos.${name}.auto_merge`) }) };
+  }
+  return result;
+}
+
 /** `version` is the running hub's, which closes the #481 S8 window; the daemon and Tasks pass it. Without one the window is open. */
 export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   if (value === undefined) return { mode: "off", requiredChecks: [], stages: [...SDLC_STAGES] };
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc: expected a table");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
+  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands", "auto_merge", "repos"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
   const maxNits = raw.max_nits === undefined ? DEFAULT_MAX_NITS : raw.max_nits;
   if (typeof maxNits !== "number" || !Number.isSafeInteger(maxNits) || maxNits < 0 || maxNits > 64) throw new Error("sdlc.max_nits: expected an integer from 0 to 64");
   const bands = bandsConfig(raw.bands), bandConfig = Object.keys(bands).length ? { bands } : {};
@@ -150,12 +192,13 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   if (workflow !== "none" && workflow !== "gsd-lite") throw new Error("sdlc.workflow: expected none or gsd-lite");
   const notes = workflow === "gsd-lite" ? [`sdlc.workflow = "gsd-lite" is deprecated and stops loading in ${RETIRED_WORKFLOW_FROM} (#481): remove it; every task then needs a criteria checklist recorded with hub_sdlc_record`] : [];
   const phaseAlias = { allowed: window, used: false };
-  const checks = raw.required_checks ?? [];
-  if (!Array.isArray(checks) || checks.length > 32 || checks.some(c => typeof c !== "string" || !c.trim() || c.length > 120 || /[\r\n\x00-\x1f]/.test(c)) || new Set(checks).size !== checks.length) throw new Error("sdlc.required_checks: expected at most 32 unique nonempty names");
+  const checks = checkList(raw.required_checks ?? [], "sdlc.required_checks");
+  // #786: absent keys add nothing to the config, so the off-mode default keeps its #257 shape byte for byte.
+  const mergeConfig = { ...(raw.auto_merge === undefined ? {} : { autoMerge: autoMergeMode(raw.auto_merge, "sdlc.auto_merge") }), ...(raw.repos === undefined ? {} : { repos: mergeRepos(raw.repos)! }) };
   if (raw.definitions !== undefined) {
     const custom = definitions(raw.definitions, raw.stages, phaseAlias);
     if (phaseAlias.used) notes.push(`the sdlc phase gate is deprecated and stops loading in ${RETIRED_WORKFLOW_FROM} (#481): name it criteria`);
-    return { mode, ...findingConfig, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
+    return { mode, ...findingConfig, ...mergeConfig, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
   }
   // Off keeps the #257 seven stages byte for byte; an enabled lifecycle defaults to the playbook (#481 S0).
   const given = raw.stages ?? (mode === "off" ? [...SDLC_STAGES] : [...PLAYBOOK_STAGES]);
@@ -163,7 +206,7 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   // An enabled #257 list keeps its order under canonical ids, so implement/verify stay read-only aliases there too.
   const stages = mode !== "off" && exactly(SDLC_STAGES) ? SDLC_STAGES.map(canonicalStage) : given;
   if (!exactly(SDLC_STAGES) && !exactly(PLAYBOOK_STAGES)) throw new Error(`sdlc.stages: use ${PLAYBOOK_STAGES.join(", ")} in that order (or the #257 list ${SDLC_STAGES.join(", ")}); other lists need definitions`);
-  return { mode, ...findingConfig, requiredChecks: [...checks] as string[], stages: [...stages as string[]], ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
+  return { mode, ...findingConfig, ...mergeConfig, requiredChecks: [...checks] as string[], stages: [...stages as string[]], ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
 }
 
 export function loadSdlc(cwd: string, version?: string): SdlcConfig {
@@ -213,6 +256,7 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
 
 function receiptIdentity(next: SdlcReceipt, previous: SdlcReceipt, raw: Record<string, unknown>): SdlcReceipt {
   const checklist = raw.criteria ?? raw.phase;
+  if (next.repo !== previous.repo || next.pr !== previous.pr || next.head !== previous.head || next.reviewedHead !== previous.reviewedHead || next.localHead !== previous.localHead) delete next.merge;
   // A test receipt never carries across a different linked issue or artifact.
   if (raw.redFirst === undefined && (next.repo !== previous.repo || next.issue !== previous.issue || next.pr !== previous.pr)) delete next.redFirst;
   // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
@@ -272,7 +316,8 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     review: p.reviewDecision === "APPROVED" ? "approved" : p.reviewDecision === "CHANGES_REQUESTED" ? "changes_requested" : "unknown",
     pendingReviews: Array.isArray(p.reviewRequests) && p.reviewRequests.length <= 100 && p.reviewRequests.every((r: unknown) => !!r && typeof r === "object") ? p.reviewRequests.length : null,
     unresolved: Number.isSafeInteger(p.unresolvedThreads) && p.unresolvedThreads >= 0 ? p.unresolvedThreads : null,
-    ...(sha(p.mergeCommit?.oid) ? { mergeCommit: p.mergeCommit.oid } : {}) };
+    ...(sha(p.mergeCommit?.oid) ? { mergeCommit: p.mergeCommit.oid } : {}),
+    ...(typeof p.headRefName === "string" && p.headRefName && p.headRefName.length <= 200 && !/[\x00-\x1f\x7f]/.test(p.headRefName) ? { headBranch: p.headRefName } : {}) };
 }
 
 /** Issue identity and edit times only; no body is fetched or stored. `lastEditedAt` moves on a body edit, not on comments. */
@@ -351,7 +396,7 @@ export function touchingPrs(prs: { pr: number; paths: string[] }[]): { before: n
 }
 
 export type SdlcGh = (args: string[], timeoutMs?: number, cwd?: string, maxOutputBytes?: number) => Promise<{ code: number; stdout: string }>;
-/** Read-only, fixed argv. Output and time are bounded; diagnostics never expose credentials or remote text. */
+/** Fixed argv and bounded output and time; diagnostics never expose credentials or remote text. Reads, except the one guarded `gh pr merge` that `sdlc-merge.ts` builds (#786). */
 export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 256 * 1024) => new Promise((resolve) => {
   const outputLimit = Number.isSafeInteger(maxOutputBytes) ? Math.min(2 * 1024 * 1024, Math.max(1, maxOutputBytes)) : 256 * 1024;
   let child: ReturnType<typeof spawn>;
@@ -409,7 +454,7 @@ export function linkedReceipt(previous: SdlcReceipt | undefined, link: { repo: s
 export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh, withIntegrity = false): Promise<PrEvidence | undefined> {
   if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
   try {
-    const view = await run(["pr", "view", String(receipt.pr), "--repo", receipt.repo, "--json", "headRefOid,state,statusCheckRollup,reviewDecision,reviewRequests,files,changedFiles,mergeCommit,isDraft,baseRefName,baseRefOid"]);
+    const view = await run(["pr", "view", String(receipt.pr), "--repo", receipt.repo, "--json", "headRefOid,state,statusCheckRollup,reviewDecision,reviewRequests,files,changedFiles,mergeCommit,isDraft,baseRefName,baseRefOid,headRefName"]);
     if (view.code !== 0) return undefined;
     const [owner, name] = receipt.repo.split("/");
     // The enabled S4 label read shares the existing thread snapshot, never a second readback for a known non-bug.
@@ -468,10 +513,11 @@ export function reviewReadinessFromEvidence(evidence: PrEvidence | undefined, ex
   else if (evidence.head !== expected) blockers.push("review head changed");
   if (evidence.state !== "OPEN") blockers.push("review PR is not open");
   if (!checks.every(name => { const matched = evidence.checks.filter(check => check.name === name); return matched.length === 1 && matched[0]?.state === "passed"; })) blockers.push("exact-head full CI is not green");
-  return { head: evidence.head, ready: blockers.length === 0, blockers };
+  return { head: evidence.head, ready: blockers.length === 0, blockers, checks };
 }
 
-export interface ReviewReadiness { head?: string; ready: boolean; blockers: string[]; reusedRun?: number }
+/** `checks` (#824) names the required checks that were judged, so a fresh reviewer can be told which ones passed at this head; absent when the read was unknown. */
+export interface ReviewReadiness { head?: string; ready: boolean; blockers: string[]; reusedRun?: number; checks?: string[] }
 /** Metadata-only pre-review admission; no remote body or comment text is requested. */
 export async function readReviewReadiness(receipt: SdlcReceipt, expected: string | undefined, run: SdlcGh = sdlcGh, requiredChecks: readonly string[] = []): Promise<ReviewReadiness> {
   const unknown = (): ReviewReadiness => ({ ready: false, blockers: ["review readiness unavailable"] });
@@ -533,7 +579,7 @@ export async function readReviewReadiness(receipt: SdlcReceipt, expected: string
       }
       if (unanswered) blockers.push("bot review threads unanswered");
     }
-    return { head: pr.headRefOid, ready: blockers.length === 0, blockers: [...new Set(blockers)], ...(reusedRun !== undefined ? { reusedRun } : {}) };
+    return { head: pr.headRefOid, ready: blockers.length === 0, blockers: [...new Set(blockers)], checks: [...full], ...(reusedRun !== undefined ? { reusedRun } : {}) };
   } catch { return unknown(); }
 }
 

package/src/hub/settings.ts

@@ -1,3 +1,4 @@
+import { operationalRosterSetting, operationalSetting } from "./operational-authority.ts";
 import { ACTION_CLASSES } from "./action-class.ts";
 import { definitionOf, type KindMap, type ProjectAdapterCatalog, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { createHash } from "node:crypto";
@@ -193,12 +194,15 @@ export function parseSettingText(def: SettingDef, text: string): unknown {
 }
 export const settingText = (value: unknown): string => value === null || value === undefined ? "(not set)" : Array.isArray(value) ? value.join(",") || "(none)" : String(value);
 
+export type SettingSource = "dashboard" | "terminal" | "conductor";
+export type SettingWriteOptions = { preserveUndo?: boolean };
 /** `ordinary`: a dashboard session from `ahub ui`. `settings`: one from `ahub ui --settings`. `terminal`: `ahub settings`. */
-export type SettingAuthority = "ordinary" | "settings" | "terminal";
+export type SettingAuthority = "ordinary" | "settings" | "terminal" | "conductor";
 /** Why this authority may not set this value, or undefined. Removing a stored value can raise, so it counts as one. */
 export function settingRefusal(def: SettingDef | string, value: SettingValue, authority: SettingAuthority): string | undefined {
   if (typeof def === "string") return def || "invalid setting definition";
   if (def.locked) return def.locked;
+  if (authority === "conductor") return operationalSetting(def) || operationalRosterSetting(def) ? undefined : `${def.key} is not an operational conductor setting`;
   if (def.risk === "safe" || authority !== "ordinary") return undefined;
   if (value !== null && value === def.floor) return undefined;
   return `${def.key} can widen what agents do without asking: open a settings session with ahub ui --settings, or use ahub settings in a terminal`;
@@ -244,10 +248,12 @@ function refuseTracked(cwd: string, file: StoredFile): void {
   // Unknown is not untracked where there is a repository to ask; only a project outside git has nothing tracked.
   if (tracked === undefined && configRepositoryPresent(cwd)) throw new Error(`git could not confirm that .agenthub/${file} is untracked; nothing was written`);
 }
-/** Keeps the one previous version, then replaces (or removes) the file. */
-function store(cwd: string, stateDir: string, file: StoredFile, key: string, previous: string | null, next: string | null): void {
+/** Person writes keep the one previous version; conductor writes preserve that existing receipt. */
+function store(cwd: string, stateDir: string, file: StoredFile, key: string, previous: string | null, next: string | null, options: SettingWriteOptions = {}): void {
   refuseTracked(cwd, file);
   replaceFile(join(cwd, ".agenthub", file), file, next);
+  // A conductor write never replaces, deletes or rebases the person's undo receipt. The ordinary digest fence still applies.
+  if(options.preserveUndo)return;
   // The record follows the file: a write that failed leaves the earlier record valid, because the file is as it left it.
   const record: UndoRecord = { file, key, previous, written: digest(next), at: Date.now() };
   try {
@@ -282,7 +288,7 @@ export function valueAt(doc: unknown, path: readonly string[]): unknown {
  * Sets (or with null removes) one key of `.agenthub/config.local.json`. `validate` gets a scratch project that holds
  * the shared config and the candidate, and throws when the hub's own loader would refuse it: nothing is written then.
  */
-export function writeConfigSetting(cwd: string, stateDir: string, def: SettingDef, value: SettingValue, validate: (scratch: string) => unknown): boolean {
+export function writeConfigSetting(cwd: string, stateDir: string, def: SettingDef, value: SettingValue, validate: (scratch: string) => unknown, options: SettingWriteOptions = {}): boolean {
   const file = join(cwd, ".agenthub", CONFIG_LOCAL);
   const before = readText(file);
   const doc = before === null ? {} : parseObject(before, CONFIG_LOCAL);
@@ -315,7 +321,7 @@ export function writeConfigSetting(cwd: string, stateDir: string, def: SettingDe
   } else node[leaf] = value;
   const text = `${JSON.stringify(doc, null, 2)}\n`;
   checkConfigText(cwd, text, validate);
-  store(cwd, stateDir, CONFIG_LOCAL, def.key, before, text);
+  store(cwd, stateDir, CONFIG_LOCAL, def.key, before, text, options);
   return true;
 }
 /** Runs `validate` on a scratch project holding the shared config and this candidate for the machine-local one. */

package/src/hub/snapshots.ts

@@ -546,6 +546,66 @@ export interface TurnRecord {
   native: string | null;
 }
 
+/**
+ * Parse `git status --porcelain=v2 -z` output into the paths of dirty submodules (#798 D2). A submodule's
+ * uncommitted edits never move the superproject's gitlink, so a diff of two snapshot trees cannot see them.
+ * Submodule entries are the only ones whose mode field starts with `S`; `N` (normal) entries never qualify.
+ */
+export function parseDirtySubmodules(z: string): string[] {
+  const entries = z.split("\0");
+  const found = new Set<string>();
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!;
+    if (entry === "") continue;
+    const kind = entry[0];
+    if (kind === "1") {
+      // `1 XY SUB mH mI mW hH hI PATH`: the rest carries 7 spaces, so the path starts after the last one.
+      const rest = entry.slice(2);
+      const cut = nthSpace(rest, 6);
+      const path = cut < 0 ? "" : rest.slice(cut + 1);
+      if (path && submoduleField(rest.slice(0, cut))) found.add(path);
+    } else if (kind === "2") {
+      // `2 XY SUB mH mI mW hH hI Xscore PATH`, then the next entry is the original path: skip it.
+      const rest = entry.slice(2);
+      const cut = nthSpace(rest, 7);
+      const path = cut < 0 ? "" : rest.slice(cut + 1);
+      if (path && submoduleField(rest.slice(0, cut))) found.add(path);
+      i++;
+    } else if (kind === "u") {
+      // `u XY SUB m1 m2 m3 mW h1 h2 h3 PATH`: nine spaces in the rest, then the path.
+      const rest = entry.slice(2);
+      const cut = nthSpace(rest, 8);
+      const path = cut < 0 ? "" : rest.slice(cut + 1);
+      if (path && submoduleField(rest.slice(0, cut))) found.add(path);
+    }
+    // `?`, `!` and `#` entries carry no mode field: ignore them.
+  }
+  return [...found].sort();
+}
+
+/** porcelain-v2 fields are `XY SUB ...`: the submodule marker is the first character of the second field. */
+const submoduleField = (fields: string): boolean => fields.slice(3, 4) === "S";
+/** Index of the nth space (0-based) after the leading kind character, or -1 when the entry is malformed. */
+function nthSpace(rest: string, n: number): number {
+  let at = -1;
+  for (let seen = 0; seen <= n; seen++) {
+    at = rest.indexOf(" ", at + 1);
+    if (at < 0) return -1;
+  }
+  return at;
+}
+
+/**
+ * Dirty submodules of a repository: modified, untracked or new commits inside a submodule worktree are invisible
+ * to snapshot tree diffs (#798 D2). Returns undefined when git cannot answer. A project without `.gitmodules`
+ * pays no git call at all (D4).
+ */
+export function dirtySubmodules(repo: Repo, budget?: SnapshotBudget): string[] | undefined {
+  if (repo.shadow || !existsSync(join(repo.top, ".gitmodules"))) return [];
+  const result = git(repo, ["status", "--porcelain=v2", "-z", "--ignore-submodules=none", "--", scope(repo)], { GIT_OPTIONAL_LOCKS: "0" }, budget, 1024 * 1024);
+  return result.status === 0 ? parseDirtySubmodules(result.stdout) : undefined;
+}
+
 /** Turn records in hub.db: the daemon writes them, `ahub turns` and `ahub undo` read them. */
 export class Turns {
   private readonly db: Database;

package/src/hub/task-repository.ts

@@ -1,7 +1,9 @@
+import { spawnSync } from "node:child_process";
 import { statSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import type { TaskPlan, TaskRefs } from "./board.ts";
-import { hubGitSync } from "./git.ts";
+import { hubGitArgv, hubGitEnv, hubGitSync } from "./git.ts";
+import { hostExecutable } from "./host-executable.ts";
 import { canonicalPath, realPath } from "./project.ts";
 import { isGitHubRepository } from "./spec-read.ts";
 
@@ -22,6 +24,33 @@ function slug(value: string): string | undefined {
   } catch { return undefined; }
 }
 
+/** Share the advisory reader's bounds; only authority reads pin Git and isolate the actual checkout. */
+function boundedGit(dir: string, args: string[], isolated = false): string | undefined {
+  try {
+    const options = { encoding: "utf8" as const, timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BYTES };
+    const argv = ["-C", dir, ...args];
+    const found = isolated
+      ? spawnSync(hostExecutable("git", dir), hubGitArgv(argv).slice(1), { ...options, cwd: dir, env: hubGitEnv(process.env, { repositoryIsolation: true }) })
+      : hubGitSync(argv, options);
+    return found.status === 0 && typeof found.stdout === "string" && found.stdout.trim() ? isolated ? found.stdout : found.stdout.trim() : undefined;
+  } catch { return undefined; } // Unknown identity never grants; never log remote URLs or stderr.
+}
+
+/** Actual project-local GitHub origin only, never task refs, a bare slug or global-config fallback. */
+export function githubOriginRepository(cwd: string): string | undefined {
+  let root: string;
+  try { root = realPath(cwd); } catch { return undefined; }
+  const reply = boundedGit(root, ["config", "--show-scope", "--get", "remote.origin.url"], true);
+  const remote = reply && /^(?:local|worktree)\t([^\r\n]+)\n$/.exec(reply)?.[1];
+  if (!remote || /[\s?#]/.test(remote)) return undefined;
+  const scp = /^(?:[^/@:]+@)?github\.com:[^/]+\/[^/]+\/?$/i.test(remote);
+  if (!scp) {
+    if (!/^(?:https?|ssh):\/\/(?:[^/@]+@)?github\.com(?::[0-9]+)?\//i.test(remote)) return undefined;
+    try { const url = new URL(remote); if (url.search || url.hash) return undefined; } catch { return undefined; }
+  }
+  return slug(remote);
+}
+
 /** Repository metadata is advisory, never an execution root or a grant. Git reads are bounded, local and cached. */
 export class TaskRepositories {
   readonly project: TaskRepository;
@@ -37,10 +66,7 @@ export class TaskRepositories {
     this.roots.set(root, this.project);
   }
   private git(dir: string, args: string[]): string | undefined {
-    try {
-      const found = hubGitSync(["-C", dir, ...args], { encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BYTES });
-      return found.status === 0 && typeof found.stdout === "string" && found.stdout.trim() ? found.stdout.trim() : undefined;
-    } catch { return undefined; } // Unknown identity keeps a path key; never log remote URLs or stderr.
+    return boundedGit(dir, args);
   }
   private directory(path: string): string {
     let cursor = resolve(path);

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;
+  }
+}