@staix/agent-hub 0.26.0 → 0.28.0

package/src/cli/init-prompt.ts

@@ -0,0 +1,179 @@
+/**
+ * #1065 T2: the guided prompt of `ahub init` for a person in a terminal on a new project.
+ *
+ * It asks one question per setting of the spec's table, in the table's order, one line each: the label, the choices and the default in brackets. Enter keeps the default and leaves
+ * that setting out of the request; any other answer is an explicit choice, exactly as the equivalent flag is (so typing the default is `--coordination advisory`, which writes the
+ * key). Unknown input asks again and never guesses. When every question is answered it shows the plan, in the words `--dry-run` prints, and asks y/N. N, an empty answer, end of
+ * input and Ctrl-C write nothing. What it returns are the values the flags would have set, so the files it leads to are the files the equivalent flags write (AC4); nothing here
+ * writes or reads a file.
+ *
+ * Who is offered it is decided by `promptGate`: a person at a terminal, on a new project, with no setting flag and no `--yes`. A delegated peer, a live test and any run without a
+ * terminal never reach `runInitPrompt` and get defaults plus their flags (AC5).
+ */
+import { INIT_SETTINGS, SDLC_MODES, SPEC_REVIEW_MODES, COORDINATION_MODES, AUTONOMY_CHOICES, type InitSettingRow, type InitSettingsRequest } from "./init-settings.ts";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PROFILE_NAMES } from "../hub/profiles.ts";
+import { DEFAULT_CONFIG } from "../hub/daemon.ts";
+import { DEFAULT_SPECS_CONFIG } from "../hub/specs-config.ts";
+import { START_AGENTS_ALLOWED, START_AGENTS_DEFAULT } from "../hub/start-agents.ts";
+
+/** What a prompt needs from its surroundings. `ask` resolves to `null` at the end of input and after Ctrl-C (the caller turns both into `null`); it never throws for either. */
+export interface InitPromptPorts {
+  ask(question: string): Promise<string | null>;
+  print(line: string): void;
+}
+
+/** Everything the questions set: the settings request the flags build, plus the three choices that are not settings rows. */
+export interface InitAnswers { request: InitSettingsRequest; profile?: string; shadow: boolean; releaseGuard: boolean }
+
+/** `declined`: the person answered no. `interrupted`: end of input or Ctrl-C. `refused`: a question got no valid answer in three tries. Nothing is written in any of the three. */
+export type InitPromptResult = { ok: true; answers: InitAnswers } | { ok: false; reason: "declined" | "interrupted" | "refused"; message: string };
+
+/** The four questions that are choices of `ahub init` but not rows of the settings table. */
+const NOT_ROWS: ReadonlySet<string> = new Set(["profile", "autonomy", "release-guard", "shadow"]);
+const MAX_TRIES = 3;
+const NOTHING = "nothing was written";
+const yes = (text: string) => /^(y|yes)$/i.test(text.trim());
+const word = (text: string) => text.trim().toLowerCase();
+
+export interface InitQuestion {
+  /** The `INIT_SETTINGS` id, or `profile`, `autonomy`, `release-guard`, `shadow` for the four choices that are not rows. */
+  id: string;
+  label: string;
+  choices: string;
+  /** The default in brackets: what an empty answer keeps. */
+  shown: string;
+  /** Reads an answer into the value to put in the answers, or throws a reason that names the allowed values. */
+  read(text: string): unknown;
+}
+
+/**
+ * The defaults the brackets show, read from where the writer gets them so a change there cannot leave the prompt showing a wrong one while Enter writes the real one: the shipped
+ * `templates/config.json` for the keys it carries (memory, snapshots, each adapter switch, specs), the loader's own `DEFAULT_CONFIG` for coordination, and the specs config defaults. A key neither
+ * source has throws, naming the key, so a new row without a known default is a loud failure in `test/init-prompt.test.ts` and not a guess.
+ */
+const TEMPLATE = JSON.parse(readFileSync(join(import.meta.dir, "..", "..", "templates", "config.json"), "utf8")) as Record<string, unknown>;
+const at = (doc: unknown, path: readonly string[]): unknown => path.reduce<unknown>((node, key) => node && typeof node === "object" ? (node as Record<string, unknown>)[key] : undefined, doc);
+export function shownDefault(id: string): string {
+  const row = INIT_SETTINGS.find(entry => entry.id === id);
+  if (!row) throw new Error(`no init setting ${id}`);
+  const path = row.path as readonly string[];
+  const fromTemplate = row.file === "config.json" ? at(TEMPLATE, path) : undefined;
+  const value = fromTemplate !== undefined ? fromTemplate
+    : id === "coordination" ? DEFAULT_CONFIG.coordination
+    : id === "specs.enabled" ? DEFAULT_SPECS_CONFIG.enabled
+    : id === "specs.review" ? DEFAULT_SPECS_CONFIG.review
+    : id === "sdlc.mode" ? "off"                    // no file is written for it: the loader's own default (src/hub/sdlc.ts)
+    : row.id.endsWith(".enabled") ? false           // a legacy `<kind>.enabled` switch that the template does not carry reads as off
+    : undefined;
+  if (typeof value === "boolean") return value ? "on" : "off";
+  if (typeof value === "string") return value;
+  throw new Error(`the shown default of ${id} is unknown: add it to templates/config.json or to shownDefault`);
+}
+
+const onOff = (id: string, label: string, shown: "on" | "off"): InitQuestion => ({
+  id, label, choices: "on|off", shown,
+  read: text => { const w = word(text); if (["on", "y", "yes", "true"].includes(w)) return true; if (["off", "n", "no", "false"].includes(w)) return false; throw new Error("answer on or off"); },
+});
+const oneOf = (id: string, label: string, values: readonly string[], shown: string): InitQuestion => ({
+  id, label, choices: values.join("|"), shown,
+  read: text => { const w = word(text); if (values.includes(w)) return w; throw new Error(`answer one of ${values.join(", ")}`); },
+});
+
+export interface InitQuestionContext {
+  /** The agent set `ahub setup` chose on this machine (the default shown for the agents question), or `undefined` for the shipped default. */
+  machineAgents?: readonly string[];
+  /** Project packs a profile answer may name besides the shipped profiles. */
+  packs?: readonly string[];
+  /** Shadow history is offered only for a folder with no Git work tree. */
+  shadowAvailable?: boolean;
+}
+
+/**
+ * The questions, in the order of the spec's table: profile, agents, specs, spec review, SDLC, coordination, memory, snapshots, each adapter's enable switch, machine autonomy, release
+ * guard and shadow history. A settings row is asked only while `INIT_SETTINGS` has it, and a row the table gains is caught by the test that compares the two.
+ */
+export function initQuestions(context: InitQuestionContext = {}): InitQuestion[] {
+  const ids = new Set(INIT_SETTINGS.map(row => row.id));
+  const packs = context.packs ?? [];
+  const profile: InitQuestion = {
+    id: "profile", label: "Profile", choices: [...PROFILE_NAMES, ...packs].join("|"), shown: "dev",
+    read: text => { const w = text.trim(); if ((PROFILE_NAMES as readonly string[]).includes(w) || packs.includes(w)) return w; throw new Error(`answer one of ${[...PROFILE_NAMES, ...packs].join(", ")}`); },
+  };
+  const agents: InitQuestion = {
+    id: "start.agents", label: "Agents ahub up starts", choices: `${START_AGENTS_ALLOWED.join(",")} as a comma list, or none`, shown: (context.machineAgents ?? START_AGENTS_DEFAULT).join(", ") || "none",
+    read: text => INIT_SETTINGS.find(row => row.id === "start.agents")!.parse(text.trim().toLowerCase()),
+  };
+  const switches = INIT_SETTINGS.filter(row => row.id.endsWith(".enabled") && !["specs.enabled", "memory.enabled", "snapshots.enabled"].includes(row.id));
+  const all: InitQuestion[] = [
+    profile,
+    agents,
+    onOff("specs.enabled", "Design specs and their freshness checks", shownDefault("specs.enabled") as "on" | "off"),
+    oneOf("specs.review", "Spec review mode", SPEC_REVIEW_MODES, shownDefault("specs.review")),
+    oneOf("sdlc.mode", "SDLC mode", SDLC_MODES, shownDefault("sdlc.mode")),
+    oneOf("coordination", "Coordination", COORDINATION_MODES, shownDefault("coordination")),
+    onOff("memory.enabled", "Shared memory", shownDefault("memory.enabled") as "on" | "off"),
+    onOff("snapshots.enabled", "Per-turn snapshots", shownDefault("snapshots.enabled") as "on" | "off"),
+    ...switches.map(row => onOff(row.id, row.describe.charAt(0).toUpperCase() + row.describe.slice(1), shownDefault(row.id) as "on" | "off")),
+    oneOf("autonomy", "Machine autonomy preset", AUTONOMY_CHOICES, "inherit"),
+    onOff("release-guard", "Release guard (AGENTS.md block and pre-push hook)", "off"),
+    ...(context.shadowAvailable ? [onOff("shadow", "Shadow history (a folder with no Git work tree)", "off")] : []),
+  ];
+  return all.filter(question => NOT_ROWS.has(question.id) || ids.has(question.id));
+}
+
+/** The question line: `label (a|b|c) [default]: `. */
+export const questionLine = (question: InitQuestion): string => `${question.label} (${question.choices}) [${question.shown}]: `;
+
+/**
+ * Asks every question, then the confirmation. `preview` turns the answers into the lines of the plan; the caller runs the same planner `--dry-run` runs, so what is shown is what is
+ * written, and a throw from it (a custom hooks path under the release guard, a config the loader refuses) ends the prompt with its message and no write.
+ */
+export async function runInitPrompt(ports: InitPromptPorts, context: InitQuestionContext, preview: (answers: InitAnswers) => string[]): Promise<InitPromptResult> {
+  const answers: InitAnswers = { request: { values: {} }, shadow: false, releaseGuard: false };
+  ports.print("ahub init: press Enter to keep the default in brackets. N at the end, Ctrl-C or Ctrl-D writes nothing.");
+  for (const question of initQuestions(context)) {
+    let settled = false;
+    for (let attempt = 0; attempt < MAX_TRIES && !settled; attempt++) {
+      const answer = await ports.ask(questionLine(question));
+      if (answer === null) return { ok: false, reason: "interrupted", message: NOTHING };
+      if (!answer.trim()) { settled = true; break; }                       // Enter: the default, and nothing is set for this question
+      try {
+        const value = question.read(answer);
+        if (question.id === "profile") answers.profile = value as string;
+        else if (question.id === "autonomy") answers.request.autonomy = value as typeof AUTONOMY_CHOICES[number];
+        else if (question.id === "release-guard") answers.releaseGuard = value as boolean;
+        else if (question.id === "shadow") answers.shadow = value as boolean;
+        else answers.request.values[question.id] = value;
+        settled = true;
+      } catch (error) { ports.print(`  ${(error as Error).message}; asking again`); }
+    }
+    if (!settled) return { ok: false, reason: "refused", message: `no valid answer for "${question.label}" after ${MAX_TRIES} tries, so ${NOTHING}; run ahub init again, or pass the setting as a flag` };
+  }
+  let lines: string[];
+  try { lines = preview(answers); } catch (error) { return { ok: false, reason: "refused", message: `${(error as Error).message}` }; }
+  ports.print(lines.length ? `This will be written:\n${lines.join("\n")}` : "Nothing differs from the defaults; the project gets the shipped configuration.");
+  const confirm = await ports.ask("Write this? [y/N]: ");
+  if (confirm === null) return { ok: false, reason: "interrupted", message: NOTHING };
+  if (!yes(confirm)) return { ok: false, reason: "declined", message: NOTHING };
+  return { ok: true, answers };
+}
+
+/**
+ * Whether the shadow-history question is asked: shadow history exists for a folder with no Git work tree, so an absent repository is eligible (that is the case it is for), a shadow repository that is
+ * already there is eligible too (`--shadow` accepts it), and a real Git work tree is not (`ahub init --shadow` refuses it).
+ */
+export const shadowOffered = (repo: { shadow?: boolean } | undefined): boolean => repo === undefined || repo.shadow === true;
+
+/** The rows of the plan in the words `ahub init --dry-run` prints, so the prompt and the preview cannot disagree. */
+export const settingLines = (rows: readonly InitSettingRow[]): string[] =>
+  rows.map(row => `  ${row.key}: ${row.from === undefined ? "(not set)" : JSON.stringify(row.from)} -> ${JSON.stringify(row.to)} (${row.file})`);
+
+/**
+ * Whether a run is offered the prompt: a person (the console role, not a delegated peer or a live test) at a terminal (stdin and stdout), on a new project, with no flag of any kind
+ * that sets something and no `--yes`. Every other run gets defaults plus its flags and is never asked anything.
+ */
+export function promptGate(input: { newProject: boolean; flagGiven: boolean; yes: boolean; dryRun: boolean; stdinIsTTY: boolean; stdoutIsTTY: boolean; role: string; delegated: boolean; liveTest: boolean }): boolean {
+  return input.newProject && !input.flagGiven && !input.yes && !input.dryRun && input.stdinIsTTY && input.stdoutIsTTY && input.role === "console" && !input.delegated && !input.liveTest;
+}

package/src/cli/init-settings.ts

@@ -0,0 +1,229 @@
+/**
+ * #1065 T1: the settings `ahub init` can set, as one table. A row names the flag, the file and key it writes, the closed set of values it accepts and how
+ * to read it back, so a new setting (the specs rows of #1064 T3) is one more row here and nothing else. Executables, secrets, models, providers, instances
+ * and permissions are deliberately not rows: they stay file edits.
+ *
+ * Pure: this module reads and writes no file. `planInitSettings` takes the current text of the three files and returns the next text of those it changes
+ * plus one row per changed key (`{ key, file, from, to }`, values from closed sets, so nothing secret can appear in a preview).
+ */
+import { checkStartAgents, START_AGENTS_ALLOWED } from "../hub/start-agents.ts";
+import { editSdlcText } from "../hub/config-edit.ts";
+import { ADAPTERS } from "../adapters/registry.ts";
+
+export type InitSettingFile = "config.json" | "config.local.json" | "sdlc.toml";
+export const SDLC_MODES = ["off", "advise", "enforce"] as const;
+export const COORDINATION_MODES = ["advisory", "turn-free"] as const;
+export const AUTONOMY_CHOICES = ["inherit", "off"] as const;
+export const SPEC_REVIEW_MODES = ["off", "report", "require"] as const;
+
+/** One changed key, as `ahub init --dry-run --json` shows it. `from` is `undefined` (absent in JSON) when the key was not set before. */
+export interface InitSettingRow { key: string; file: InitSettingFile; from: unknown; to: unknown }
+
+interface InitSettingDef {
+  /** The request key and the row's `key` (the config path, dotted). */
+  id: string;
+  /** Flags that set it, with the value each gives: a value flag reads its argument, a switch gives a fixed value. */
+  flags: readonly { flag: string; value?: unknown }[];
+  file: InitSettingFile;
+  /** The key's path inside the file. */
+  path: readonly string[];
+  /** The closed set shown in a refusal, and in help. */
+  allowed: string;
+  /** Reads a flag's text into the value to write, or throws a reason that names the allowed values. */
+  parse(text: string): unknown;
+  /** What the setting is, for a refusal or a plan line. */
+  describe: string;
+}
+
+const choice = <T extends string>(id: string, flag: string, values: readonly T[]) => (text: string): T => {
+  if ((values as readonly string[]).includes(text)) return text as T;
+  throw new Error(`${flag}: "${text.slice(0, 48)}" is not ${values.join(", ")}; nothing was written`);
+};
+
+export const INIT_SETTINGS: readonly InitSettingDef[] = [
+  { id: "start.agents", flags: [{ flag: "--agents" }], file: "config.local.json", path: ["start", "agents"], allowed: `${START_AGENTS_ALLOWED.join(", ")} or none`, describe: "agents ahub up starts",
+    parse: text => {
+      const words = text.split(/[\s,]+/).filter(Boolean);
+      try { return checkStartAgents(words.length === 1 && words[0] === "none" ? [] : words, "--agents"); }
+      catch (error) { throw new Error(`${(error as Error).message}; allowed: ${START_AGENTS_ALLOWED.join(", ")} or none; nothing was written`); }
+    } },
+  { id: "sdlc.mode", flags: [{ flag: "--sdlc" }], file: "sdlc.toml", path: ["mode"], allowed: SDLC_MODES.join("|"), describe: "SDLC mode", parse: choice("sdlc.mode", "--sdlc", SDLC_MODES) },
+  { id: "coordination", flags: [{ flag: "--coordination" }], file: "config.json", path: ["coordination"], allowed: COORDINATION_MODES.join("|"), describe: "coordination mode", parse: choice("coordination", "--coordination", COORDINATION_MODES) },
+  { id: "memory.enabled", flags: [{ flag: "--memory", value: true }, { flag: "--no-memory", value: false }], file: "config.json", path: ["memory", "enabled"], allowed: "on|off", describe: "shared memory", parse: () => { throw new Error("unreachable"); } },
+  { id: "snapshots.enabled", flags: [{ flag: "--snapshots", value: true }, { flag: "--no-snapshots", value: false }], file: "config.json", path: ["snapshots", "enabled"], allowed: "on|off", describe: "per-turn snapshots", parse: () => { throw new Error("unreachable"); } },
+  // #1064 T3: the design-specs feature. `--no-specs` also removes the AGENT_HUB_SPECS block from AGENTS.md and `--specs` restores it (init.ts reads the planned `specs.enabled`); the key is shared, so a team commits the choice.
+  { id: "specs.enabled", flags: [{ flag: "--specs", value: true }, { flag: "--no-specs", value: false }], file: "config.json", path: ["specs", "enabled"], allowed: "on|off", describe: "design specs and their freshness checks", parse: () => { throw new Error("unreachable"); } },
+  { id: "specs.review", flags: [{ flag: "--spec-review" }], file: "config.json", path: ["specs", "review"], allowed: SPEC_REVIEW_MODES.join("|"), describe: "how a task's covering specs are reviewed", parse: choice("specs.review", "--spec-review", SPEC_REVIEW_MODES) },
+  // One row per adapter that still has a legacy `<kind>.enabled` switch in config.json (its definition says so with `enabledSwitchStartOnly`): no peer is named here, so a second
+  // such adapter gets its `--<kind>` / `--no-<kind>` flags and its row from its own definition (#451: peer policy lives in the registry, not in generic code).
+  ...ADAPTERS.filter(definition => definition.enabledSwitchStartOnly === true).map((definition): InitSettingDef => ({
+    id: `${definition.kind}.enabled`, flags: [{ flag: `--${definition.kind}`, value: true }, { flag: `--no-${definition.kind}`, value: false }],
+    file: "config.json", path: [definition.kind, "enabled"], allowed: "on|off", describe: `the ${definition.displayName} peer`, parse: () => { throw new Error("unreachable"); },
+  })),
+];
+
+/** `--autonomy inherit|off` is not a config key: it decides whether a new project inherits the machine's autonomy preset (person-only, main.ts applies it). */
+export interface InitSettingsRequest {
+  /** Keyed by `InitSettingDef.id`; absent means "not asked for", which on an existing project changes nothing. */
+  values: Record<string, unknown>;
+  autonomy?: typeof AUTONOMY_CHOICES[number];
+}
+
+/** The usage line `ahub init` prints for a bad argument; help.ts shows the same flags. */
+export const INIT_USAGE = "usage: ahub init [--profile dev|research|writing|general|<pack>] [--agents <a,b,...|none>] [--sdlc off|advise|enforce] [--coordination advisory|turn-free] [--memory|--no-memory] [--snapshots|--no-snapshots] [--pi|--no-pi] [--specs|--no-specs] [--spec-review off|report|require] [--autonomy inherit|off] [--shadow] [--release-guard] [--yes] [--dry-run --json]";
+
+/** Every flag the table and the two non-key choices own, for the caller's own argument loop and for help. */
+export const INIT_SETTING_FLAGS: readonly string[] = [...INIT_SETTINGS.flatMap(row => row.flags.map(flag => flag.flag)), "--autonomy"];
+
+/**
+ * Separates the setting flags from the rest of an `ahub init` argv. A value flag takes the next word; a switch takes none. A flag given twice with different
+ * values is refused, so the last one never silently wins. Throws a reason that names the allowed values.
+ */
+export function parseInitSettings(args: readonly string[]): { request: InitSettingsRequest; rest: string[] } {
+  const request: InitSettingsRequest = { values: {} };
+  const rest: string[] = [];
+  const set = (id: string, flag: string, value: unknown) => {
+    if (Object.hasOwn(request.values, id) && JSON.stringify(request.values[id]) !== JSON.stringify(value)) throw new Error(`${flag} conflicts with another flag for ${id}; give one; nothing was written`);
+    request.values[id] = value;
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--autonomy") {
+      const text = args[++i];
+      if (text === undefined) throw new Error(`--autonomy needs a value: ${AUTONOMY_CHOICES.join("|")}; nothing was written`);
+      if (!(AUTONOMY_CHOICES as readonly string[]).includes(text)) throw new Error(`--autonomy: "${text.slice(0, 48)}" is not ${AUTONOMY_CHOICES.join(", ")}; nothing was written`);
+      if (request.autonomy !== undefined && request.autonomy !== text) throw new Error("--autonomy was given twice with different values; give one; nothing was written");
+      request.autonomy = text as typeof AUTONOMY_CHOICES[number];
+      continue;
+    }
+    const row = INIT_SETTINGS.find(def => def.flags.some(flag => flag.flag === arg));
+    if (!row) { rest.push(arg); continue; }
+    const flag = row.flags.find(entry => entry.flag === arg)!;
+    if ("value" in flag) { set(row.id, arg, flag.value); continue; }
+    const text = args[++i];
+    if (text === undefined) throw new Error(`${arg} needs a value: ${row.allowed}; nothing was written`);
+    set(row.id, arg, row.parse(text));
+  }
+  return { request, rest };
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const valueAt = (doc: Record<string, unknown>, path: readonly string[]): unknown => path.reduce<unknown>((at, key) => isObject(at) ? at[key] : undefined, doc);
+
+// ---- A text-level JSON editor: it changes one key and leaves every other byte of the file where it was (AC2: the formatting of untouched keys is preserved). ----
+// The input is always text JSON.parse already accepted, so the scanner only has to find where values start and end.
+const skip = (text: string, at: number): number => { while (at < text.length && /\s/.test(text[at]!)) at++; return at; };
+function stringEnd(text: string, at: number): number { at++; while (text[at] !== '"') { if (text[at] === "\\") at++; at++; } return at + 1; }
+interface Member { key: string; keyStart: number; valueStart: number; valueEnd: number }
+interface ObjectSpan { start: number; end: number; members: Member[] }
+function valueEnd(text: string, from: number): number {
+  let at = skip(text, from);
+  const c = text[at];
+  if (c === '"') return stringEnd(text, at);
+  if (c === "{") return objectSpan(text, at).end;
+  if (c === "[") {
+    at = skip(text, at + 1);
+    if (text[at] === "]") return at + 1;
+    for (;;) { at = skip(text, valueEnd(text, at)); if (text[at] === ",") { at = skip(text, at + 1); continue; } return at + 1; }
+  }
+  while (at < text.length && !/[\s,\]}]/.test(text[at]!)) at++;
+  return at;
+}
+function objectSpan(text: string, start: number): ObjectSpan {
+  const members: Member[] = [];
+  let at = skip(text, start + 1);
+  if (text[at] === "}") return { start, end: at + 1, members };
+  for (;;) {
+    at = skip(text, at);
+    const keyStart = at, keyEnd = stringEnd(text, at);
+    const key = JSON.parse(text.slice(keyStart, keyEnd)) as string;
+    at = skip(text, skip(text, keyEnd) + 1);
+    const end = valueEnd(text, at);
+    members.push({ key, keyStart, valueStart: at, valueEnd: end });
+    at = skip(text, end);
+    if (text[at] === ",") { at++; continue; }
+    return { start, end: at + 1, members };
+  }
+}
+const indentOf = (text: string, at: number): string => { const lineStart = text.lastIndexOf("\n", at - 1) + 1; return /^[ \t]*/.exec(text.slice(lineStart))![0]; };
+/** A value as the project's own files write it: scalars as JSON, a list of scalars on one line, an object over lines (or one line when `inline`). */
+function render(value: unknown, indent: string, inline: boolean): string {
+  if (Array.isArray(value)) return `[${value.map(item => render(item, indent, true)).join(", ")}]`;
+  if (!isObject(value)) return JSON.stringify(value);
+  const entries = Object.entries(value);
+  if (!entries.length) return "{}";
+  if (inline) return `{ ${entries.map(([key, item]) => `${JSON.stringify(key)}: ${render(item, indent, true)}`).join(", ")} }`;
+  const inner = `${indent}  `;
+  return `{\n${entries.map(([key, item]) => `${inner}${JSON.stringify(key)}: ${render(item, inner, false)}`).join(",\n")}\n${indent}}`;
+}
+/** Sets `path` to `value` in JSON `text`, keeping everything else byte for byte. A missing key is added after the last member; a missing parent is created. */
+export function editJsonText(text: string, path: readonly string[], value: unknown): string {
+  const [head, ...tail] = path;
+  const span = objectSpan(text, skip(text, 0));
+  return editObject(text, span, head!, tail, value, indentOf(text, span.start));
+}
+function editObject(text: string, span: ObjectSpan, head: string, tail: readonly string[], value: unknown, parentIndent: string): string {
+  // JSON.parse (and so the daemon's loader) keeps the LAST occurrence of a repeated key: edit that one, or the file would read as unchanged (#1065 review).
+  const found = span.members.findLast(member => member.key === head);
+  if (found) {
+    if (!tail.length) return text.slice(0, found.valueStart) + render(value, indentOf(text, found.keyStart), !text.slice(span.start, span.end).includes("\n")) + text.slice(found.valueEnd);
+    if (text[found.valueStart] !== "{") throw new Error(`${head} in the project config is not an object, so ${[head, ...tail].join(".")} cannot be set; fix it in your editor, then run ahub init again; nothing was written`);
+    return editObject(text, objectSpan(text, found.valueStart), tail[0]!, tail.slice(1), value, indentOf(text, found.keyStart));
+  }
+  const nested = tail.reduceRight<unknown>((inner, key) => ({ [key]: inner }), value);
+  const multiline = text.slice(span.start, span.end).includes("\n") || !span.members.length;
+  if (!span.members.length) {
+    const inner = `${parentIndent}  `;
+    return `${text.slice(0, span.start)}{\n${inner}${JSON.stringify(head)}: ${render(nested, inner, false)}\n${parentIndent}}${text.slice(span.end)}`;
+  }
+  const last = span.members.at(-1)!, indent = indentOf(text, last.keyStart);
+  const member = `${JSON.stringify(head)}: ${render(nested, indent, !multiline)}`;
+  return `${text.slice(0, last.valueEnd)},${multiline ? `\n${indent}` : " "}${member}${text.slice(last.valueEnd)}`;
+}
+
+/** The current text of each file init may write (`null` when absent), and what the plan makes of them. */
+export type InitSettingTexts = Record<InitSettingFile, string | null>;
+export interface InitSettingsPlan { rows: InitSettingRow[]; next: Partial<Record<InitSettingFile, string>>; }
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+function parseJsonObject(file: string, text: string): Record<string, unknown> {
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { throw new Error(`.agenthub/${file} is not valid JSON; fix it in your editor, then run ahub init again; nothing was written`); }
+  if (!isObject(parsed)) throw new Error(`.agenthub/${file} must hold a JSON object; fix it in your editor, then run ahub init again; nothing was written`);
+  return parsed;
+}
+
+/**
+ * What the requested settings change, given the current files. `texts["config.json"]` is the text the file will have (the template, with the profile applied, for
+ * a new project). A key that already holds the requested value makes no row and no write; an absent key is written. Only the named keys change: an existing file is edited in place by
+ * `editJsonText` (and `editSdlcText` for sdlc.toml), a missing config.local.json is created with just the keys asked for. The same key given twice is
+ * refused by the parser, so each key appears at most once.
+ */
+export function planInitSettings(request: InitSettingsRequest, texts: InitSettingTexts): InitSettingsPlan {
+  const rows: InitSettingRow[] = [], next: Partial<Record<InitSettingFile, string>> = {};
+  const current: Record<"config.json" | "config.local.json", string | null> = { "config.json": texts["config.json"], "config.local.json": texts["config.local.json"] };
+  const parsed = (file: "config.json" | "config.local.json") => current[file] === null ? {} : parseJsonObject(file, current[file]!);
+  for (const row of INIT_SETTINGS) {
+    if (!Object.hasOwn(request.values, row.id)) continue;
+    const to = request.values[row.id];
+    if (row.file === "sdlc.toml") {
+      let from: unknown = "off";
+      if (texts["sdlc.toml"] !== null) {
+        try { const mode = (Bun.TOML.parse(texts["sdlc.toml"]) as Record<string, unknown>).mode; if (mode !== undefined) from = mode; }
+        catch { throw new Error(".agenthub/sdlc.toml is not valid TOML; fix it in your editor, then run ahub init again; nothing was written"); }
+      }
+      if (same(from, to)) continue; // off with no file is the shipped state: no file is written for it
+      const text = editSdlcText(next["sdlc.toml"] ?? texts["sdlc.toml"], [{ path: ["mode"], value: to }]);
+      if (text !== null) next["sdlc.toml"] = text;
+      rows.push({ key: row.id, file: "sdlc.toml", from, to });
+      continue;
+    }
+    const file = row.file, doc = parsed(file);
+    const held = valueAt(doc, row.path);
+    if (held !== undefined && same(held, to)) continue; // a key that already holds the value is a no-op; an absent key is written, so the choice is explicit and a team can commit it
+    current[file] = current[file] === null ? editJsonText("{}\n", row.path, to) : editJsonText(current[file]!, row.path, to);
+    next[file] = current[file]!;
+    rows.push({ key: row.id, file, ...(held === undefined ? {} : { from: held }), to } as InitSettingRow);
+  }
+  return { rows, next };
+}

package/src/cli/init.ts

@@ -11,6 +11,10 @@ import { realPath } from "../hub/project.ts";
 import { hubGitArgv, hubGitEnv, hubGitSync } from "../hub/git.ts";
 import { KIMI_MCP_FILE } from "./kimi-mcp.ts";
 import { AGY_PLUGIN_FILES } from "./agy-mcp.ts";
+import { loadConfig } from "../hub/daemon.ts";
+import { sdlcConfig } from "../hub/sdlc.ts";
+import { VERSION } from "../version.ts";
+import { planInitSettings, type InitSettingFile, type InitSettingRow, type InitSettingsRequest } from "./init-settings.ts";
 
 const TEMPLATES = join(import.meta.dir, "..", "..", "templates");
 const BEGIN = "<!-- AGENT_HUB:BEGIN (managed by `ahub init`, edits inside are overwritten) -->";
@@ -41,7 +45,7 @@ export interface InitChange {
   managedBlock?: "insert" | "replace" | "remove";
 }
 /** Content is internal to apply, never included in a public preview. */
-interface PlannedWrite extends InitChange { next?: string; shadow?: true; directory?: true; executable?: true; moveFrom?: string; expected?: { dev: number; ino: number }; }
+interface PlannedWrite extends InitChange { privateFile?: true; next?: string; shadow?: true; directory?: true; executable?: true; moveFrom?: string; expected?: { dev: number; ino: number }; }
 const RELEASE_BEGIN = "<!-- AGENT_HUB_RELEASE_GUARD:BEGIN (managed by `ahub init --release-guard`) -->";
 const RELEASE_END = "<!-- AGENT_HUB_RELEASE_GUARD:END -->";
 const HOOK_MARKER = "# agent-hub managed release pre-push guard";
@@ -54,6 +58,41 @@ function releaseBlock(existing: string): string {
   if (start >= 0 || existing.includes(RELEASE_END)) throw new Error("release guard instruction markers are incomplete");
   return `${existing.trimEnd()}\n\n${block}\n`;
 }
+const SPECS_BEGIN = "<!-- AGENT_HUB_SPECS:BEGIN (managed by `ahub init`, edits inside are overwritten; `ahub init --no-specs` removes it) -->";
+const SPECS_END = "<!-- AGENT_HUB_SPECS:END -->";
+/**
+ * #1064 T3: the design-specs instruction block, placed the way the release guard's is. On: insert it (at the end of the file) or replace it in place. Off: drop it and the blank
+ * lines around it, and nothing else. Text outside the markers is never touched, and incomplete markers are refused (nothing is guessed about where a half block ends).
+ */
+export function specsBlock(existing: string, enabled: boolean): string {
+  const start = existing.indexOf("<!-- AGENT_HUB_SPECS:BEGIN"), end = existing.indexOf(SPECS_END, Math.max(start, 0));
+  if (start >= 0 !== end > start || start < 0 && existing.includes(SPECS_END)) throw new Error("the AGENT_HUB_SPECS markers in AGENTS.md are incomplete; fix or remove the half block in your editor, then run ahub init again; nothing was written");
+  if (!enabled) {
+    if (start < 0) return existing;
+    // Take out the block, the line break that ends its closing marker and one separating blank line, and nothing else: whitespace belonging to the text around it
+    // (an indented code block right after the block, trailing spaces, the end of the file) is left byte for byte. With nothing before the block, the blank lines after it go instead.
+    let before = existing.slice(0, start), after = existing.slice(end + SPECS_END.length);
+    if (before === "") after = after.replace(/^(?:[ \t]*\r?\n)+/, "");
+    else { after = after.replace(/^\r?\n/, ""); if (/\r?\n\r?\n$/.test(before)) before = before.replace(/\r?\n$/, ""); }
+    const rest = before + after;
+    return rest.trim() === "" ? "" : rest;
+  }
+  const block = `${SPECS_BEGIN}\n${readFileSync(join(TEMPLATES, "specs.block.md"), "utf8").trim()}\n${SPECS_END}`;
+  if (start >= 0) return existing.slice(0, start) + block + existing.slice(end + SPECS_END.length);
+  return `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}\n`;
+}
+/** Whether the specs feature is on for what init is about to leave behind: the flag when given, else the project's own layers (config.local.json over config.json), else the shipped default (on). */
+function specsEnabled(cwd: string, settings: InitSettingsRequest | undefined): boolean {
+  const asked = settings?.values["specs.enabled"];
+  if (typeof asked === "boolean") return asked;
+  let enabled = true;
+  for (const name of ["config.json", "config.local.json"]) {
+    const path = join(cwd, ".agenthub", name);
+    if (!existsSync(path)) continue;
+    try { const value = (JSON.parse(readFileSync(path, "utf8")) as { specs?: { enabled?: unknown } }).specs?.enabled; if (typeof value === "boolean") enabled = value; } catch { /* an unreadable layer is refused elsewhere, with its own message */ }
+  }
+  return enabled;
+}
 function regularHook(file: string): Stats | undefined {
   const info = lstatSync(file, { throwIfNoEntry: false });
   if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) throw new Error("release guard hook must be an unlinked regular file");
@@ -110,7 +149,7 @@ function selection(cwd: string, requested: string | undefined): { profile?: Prof
   const bad = loaded.errors.filter(error => error.id === requested || error.id === "project").map(error => `${error.id}: ${error.reason}`);
   throw new Error(`unknown profile or pack "${requested.slice(0, 48)}"; profiles: ${PROFILE_NAMES.join(", ")}; packs in .agenthub/roles: ${[...loaded.packs.keys()].join(", ") || "none"}${bad.length ? `; not loaded: ${bad.join("; ")}` : ""}`);
 }
-function changes(cwd: string, requestedName?: string, shadow = false, releaseGuard = false): PlannedWrite[] {
+function changes(cwd: string, requestedName?: string, shadow = false, releaseGuard = false, settings?: InitSettingsRequest): { writes: PlannedWrite[]; settingRows: InitSettingRow[] } {
   const { profile: requested, pack } = selection(cwd, requestedName);
   const originalAgents = existsSync(join(cwd, "AGENTS.md")) ? readFileSync(join(cwd, "AGENTS.md"), "utf8") : "";
   const guarded = releaseGuard || originalAgents.includes("<!-- AGENT_HUB_RELEASE_GUARD:BEGIN");
@@ -131,7 +170,8 @@ function changes(cwd: string, requestedName?: string, shadow = false, releaseGua
   for (const name of ["config.json", "config.local.json"]) {
     const path = join(cwd, ".agenthub", name);
     if (existsSync(path)) {
-      const layer = JSON.parse(readFileSync(path, "utf8"));
+      let layer: Record<string, unknown>;
+      try { layer = JSON.parse(readFileSync(path, "utf8")); } catch { throw new Error(`.agenthub/${name} is not valid JSON; fix it in your editor, then run ahub init again; nothing was written`); }
       if (layer.profile !== undefined) activeProfile = profileName(layer.profile);
       resolveProfile(activeProfile, layer.profile_overrides);
       overrides = mergeProfileOverrides(overrides, layer.profile_overrides);
@@ -170,7 +210,8 @@ function changes(cwd: string, requestedName?: string, shadow = false, releaseGua
   }
   const agents = join(cwd, "AGENTS.md");
   const existing = existsSync(agents) ? readFileSync(agents, "utf8") : "";
-  const instructions = upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8"));
+  const hubBlock = upsertBlock(existing, overrides && Object.hasOwn(overrides as object, "agents") ? profile.agents : profile.agents || readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8"));
+  const instructions = specsBlock(hubBlock, specsEnabled(cwd, settings)); // #1064 T3: a project that turned specs off keeps no block
   write(agents, guarded ? releaseBlock(instructions) : instructions, "refresh hub instructions; preserve surrounding text", existing.includes("<!-- AGENT_HUB:BEGIN") ? "replace" : "insert");
   const claude = join(cwd, "CLAUDE.md");
   const own = lstatSync(claude, { throwIfNoEntry: false });
@@ -196,18 +237,69 @@ function changes(cwd: string, requestedName?: string, shadow = false, releaseGua
   }
   if (existsSync(join(cwd, JCODE_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(JCODE_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${JCODE_MCP_FILE}\n`;
   write(ignore, lines, "ignore runtime state and machine-local configuration");
-  return [...hooks, ...changed];
+  // #1065 T1: the settings table. config.json is the text it will have after the template and pack writes above; the rest is what is on disk.
+  let settingRows: InitSettingRow[] = [];
+  if (settings && (Object.keys(settings.values).length)) {
+    const planned = (path: string) => changed.find(row => row.path === path && row.next !== undefined)?.next;
+    const read = (path: string): string | null => existsSync(path) ? readFileSync(path, "utf8") : null;
+    const files: Record<InitSettingFile, string> = { "config.json": join(cwd, ".agenthub", "config.json"), "config.local.json": join(cwd, ".agenthub", "config.local.json"), "sdlc.toml": join(cwd, ".agenthub", "sdlc.toml") };
+    const texts = Object.fromEntries((Object.keys(files) as InitSettingFile[]).map(name => [name, planned(files[name]) ?? read(files[name])])) as Record<InitSettingFile, string | null>;
+    const result = planInitSettings(settings, texts);
+    settingRows = result.rows;
+    for (const name of Object.keys(result.next) as InitSettingFile[]) {
+      const path = files[name], text = result.next[name]!;
+      const row = changed.find(entry => entry.path === path);
+      const reason = `set ${result.rows.filter(entry => entry.file === name).map(entry => entry.key).join(", ")} from the init flags`;
+      if (row) { row.next = text; row.reason = `${row.reason}; ${reason}`; }
+      else changed.push({ action: existsSync(path) ? "modify" : "create", path, next: text, reason, ...(name === "config.local.json" ? { privateFile: true as const } : {}) });
+    }
+  }
+  return { writes: [...hooks, ...changed], settingRows };
+}
+/**
+ * #1065: the files init is about to write for the settings flags are checked by the loaders the daemon uses, before anything is written. A refusal
+ * names the loader's reason and writes nothing. Only the settings files are judged, so an unrelated project that already has a warning is not blocked.
+ */
+function checkCandidate(cwd: string, plan: readonly PlannedWrite[]): void {
+  const at = (name: string) => plan.find(row => row.path === join(cwd, ".agenthub", name) && row.next !== undefined)?.next;
+  const config = at("config.json"), local = at("config.local.json"), sdlc = at("sdlc.toml");
+  if (config === undefined && local === undefined && sdlc === undefined) return;
+  const layer = (name: "config.json" | "config.local.json", text: string | undefined) => {
+    const raw = text ?? (existsSync(join(cwd, ".agenthub", name)) ? readFileSync(join(cwd, ".agenthub", name), "utf8") : undefined);
+    return raw === undefined ? [] : [{ name, raw: JSON.parse(raw) as Record<string, unknown> }];
+  };
+  if (config !== undefined || local !== undefined) {
+    try { loadConfig(cwd, [...layer("config.json", config), ...layer("config.local.json", local)] as never); }
+    catch (error) { throw new Error(`the resulting .agenthub config does not pass the hub's config check: ${(error as Error).message}; fix that key in your editor, then run ahub init again; nothing was written`); }
+  }
+  if (sdlc !== undefined) {
+    try { sdlcConfig(Bun.TOML.parse(sdlc), VERSION); }
+    catch (error) { throw new Error(`the resulting .agenthub/sdlc.toml does not pass the hub's check: ${(error as Error).message}; fix it in your editor, then run ahub init again; nothing was written`); }
+  }
+}
+/**
+ * The plan row for the machine autonomy preset a new project inherits after the writes (`inheritMachineAutonomy`, run by `ahub init` once the files exist): `--dry-run` and the guided prompt's
+ * confirmation both take it from here, so the plan a person approves cannot omit it. `undefined` when nothing is inherited (the machine default is off, or the person chose `--autonomy off`).
+ */
+export function autonomyInheritanceChange(cwd: string, machineEnabled: boolean, autonomy: "inherit" | "off" | undefined): InitChange | undefined {
+  if (!machineEnabled || autonomy === "off") return undefined;
+  return { action: existsSync(join(cwd, ".agenthub/config.local.json")) ? "modify" : "create", path: join(cwd, ".agenthub/config.local.json"), reason: "inherit the trusted machine autonomy preset; consent is checked at daemon startup" };
 }
 /** What a pack adds, by id only: the preview names the criteria and checks, never their text. */
 const packReason = (pack: DomainPack, how: string) =>
   `${how} pack ${pack.name} (profile ${pack.profile}): rubric ${pack.rubric.map(item => item.id).join(", ")}; checks ${pack.checks.map(check => check.id).join(", ") || "none"}; expects roles ${pack.roles.join(", ") || "none"} from the catalog`;
 /** Read-only metadata, deliberately omitting project/user file contents. `profile` is a shipped profile name or a project pack name. */
-export function planInit(cwd: string, profile?: string, shadow = false, releaseGuard = false): InitChange[] {
-  return changes(cwd, profile, shadow, releaseGuard).map(({ next, shadow: _shadow, directory, executable, moveFrom, expected, ...change }) => change);
+export function planInit(cwd: string, profile?: string, shadow = false, releaseGuard = false, settings?: InitSettingsRequest): InitChange[] {
+  return changes(cwd, profile, shadow, releaseGuard, settings).writes.map(({ next, shadow: _shadow, directory, executable, moveFrom, expected, privateFile, ...change }) => change);
+}
+/** #1065 T1: what the settings flags change, key by key (`ahub init --dry-run --json` shows it as `settings`). Read-only. */
+export function initSettingRows(cwd: string, profile?: string, shadow = false, releaseGuard = false, settings?: InitSettingsRequest): InitSettingRow[] {
+  return changes(cwd, profile, shadow, releaseGuard, settings).settingRows;
 }
 /** Returns the paths it changed, applying the same plan as the preview. */
-export function init(cwd: string, profile?: string, shadow = false, releaseGuard = false): string[] {
-  const plan = changes(cwd, profile, shadow, releaseGuard);
+export function init(cwd: string, profile?: string, shadow = false, releaseGuard = false, settings?: InitSettingsRequest): string[] {
+  const plan = changes(cwd, profile, shadow, releaseGuard, settings).writes;
+  checkCandidate(cwd, plan);
   // Recheck hook parents and rename identities before any project write.
   for (const change of plan.filter(change => change.executable || change.moveFrom)) {
     const parent = lstatSync(dirname(change.path), { throwIfNoEntry: false });
@@ -243,6 +335,7 @@ export function init(cwd: string, profile?: string, shadow = false, releaseGuard
         throw error;
       } finally { if (lstatSync(temporary, { throwIfNoEntry: false })) unlinkSync(temporary); }
     }
+    else if (change.privateFile) { const tmp = `${change.path}.${process.pid}.tmp`; try { writeFileSync(tmp, change.next!, { mode: 0o600, flag: "wx" }); renameSync(tmp, change.path); } catch (error) { try { unlinkSync(tmp); } catch { /* nothing was written */ } throw error; } }
     else writeFileSync(change.path, change.next!);
   }
   return plan.map(change => change.path);

package/src/cli/launch.ts

@@ -55,7 +55,9 @@ export function requirePeerInstances(features: unknown): void {
 
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
 export function nativeLaunchEnv(tool: string, source: NodeJS.ProcessEnv, instances?: InstancesConfig): NodeJS.ProcessEnv {
-  const env = peerChildEnv(tool, source);
+  // This native runs in the person's own terminal and keeps that pane's Orca integration.
+  // Daemon-owned peers use peerChildEnv's default scrubbed environment.
+  const env = peerChildEnv(tool, source, { preserveOrca: true });
   delete env.AGENTHUB_UNATTENDED;
   // Channel evidence for the plugin (issue #205): set beside the development-channel flag `buildLaunch` always passes.
   const definition = definitionOf(tool, instances);