@maycombhq/atticus 2.0.0-beta.21 → 2.0.0-beta.23

package/dist/packages/sdk/npm/index.js

@@ -1273,16 +1273,24 @@ var MetarepoStamp = z4.strictObject({
 });
 
 // packages/core/dist/schema/question.js
-var QUESTION_SCHEMA_VERSION = 5;
+var QUESTION_SCHEMA_VERSION = 6;
 var QuestionSchemaVersion = z5.union([
   z5.literal(1),
   z5.literal(2),
   z5.literal(3),
   z5.literal(4),
+  z5.literal(5),
   z5.literal(QUESTION_SCHEMA_VERSION)
 ]).overwrite(() => QUESTION_SCHEMA_VERSION);
 var QUESTION_ROLES = ["product", "architecture", "analysis", "delivery"];
 var QuestionRole = z5.enum(QUESTION_ROLES);
+var QUESTION_ASKS = ["business", "design", "delivery"];
+var QuestionAsks = z5.enum(QUESTION_ASKS);
+var QuestionRouted = z5.strictObject({
+  from: QuestionRole.optional(),
+  by: z5.string().trim().min(1),
+  at: IsoDateTime
+});
 var AI_RUNTIMES = ["copilot-acp", "hand-off"];
 var DECIDE_BARS = ["confident", "agrees-with-shapes", "person-rule"];
 var DecideBar = z5.enum(DECIDE_BARS);
@@ -1413,6 +1421,10 @@ var Question = z5.strictObject({
    * that raised it unless the question said otherwise. Left out where no stage owns it.
    */
   role: QuestionRole.optional(),
+  /** Version 6 (ADR 0191): what the question asks, as the AI tagged it when it raised it. */
+  asks: QuestionAsks.optional(),
+  /** Version 6 (ADR 0191): a person re-routed it; `role` is the role they gave it. */
+  routed: QuestionRouted.optional(),
   /**
    * Version 5 (ninth UX walk): a critic knowledge gap a person routed with Ask: who it is
    * asked of (a team or a person, the finding's owner unless they named another).
@@ -1491,6 +1503,12 @@ var QuestionDraft = z5.strictObject({
    * design stage asking the product owner what the brief meant). Left out, the stage's role.
    */
   role: QuestionRole.optional(),
+  /**
+   * ADR 0191: what the question asks (business, design or delivery). It decides the role that
+   * owns it when `role` is left out, so a business question a design stage raises goes to the
+   * product owner, not the architect.
+   */
+  asks: QuestionAsks.optional(),
   /**
    * The step's own reading (ADR 0117): this question is one already on file (same), or asks
    * part of one (narrower), with the words of the earlier question that say so. Atticus checks
@@ -1667,13 +1685,41 @@ function normalizePath(input) {
   const trimmed = input.trim();
   if (trimmed === "")
     return "";
-  const withoutQuery = trimmed.split(/[?#]/, 1)[0] ?? "";
+  const withoutQuery = stripParamConstraints(trimmed).split(/[?#]/, 1)[0] ?? "";
   const isPath = withoutQuery.startsWith("/") || withoutQuery.includes("/");
   if (!isPath)
     return withoutQuery;
   const segments = withoutQuery.split("/").filter((s) => s.length > 0).map((s) => /^(\{[^}]*\}|:[^/]+|<[^>]+>|\$\{[^}]*\})$/.test(s) ? "{}" : s);
   return "/" + segments.join("/");
 }
+function stripParamConstraints(path) {
+  let out = "";
+  let i = 0;
+  while (i < path.length) {
+    const ch = path[i];
+    if (ch !== "{") {
+      out += ch;
+      i++;
+      continue;
+    }
+    let depth = 0;
+    let j = i;
+    for (; j < path.length; j++) {
+      if (path[j] === "{")
+        depth++;
+      else if (path[j] === "}" && --depth === 0)
+        break;
+    }
+    if (j >= path.length) {
+      out += path.slice(i);
+      break;
+    }
+    const inner = path.slice(i + 1, j);
+    out += "{" + (/^[^:?=]*/.exec(inner)?.[0] ?? "") + "}";
+    i = j + 1;
+  }
+  return out;
+}
 function interfaceId(from, to, method, path) {
   const key = [from, to, (method ?? "").toUpperCase(), normalizePath(path)].join("|");
   return "if-" + createHash("sha256").update(key, "utf8").digest("hex").slice(0, 16);
@@ -1769,6 +1815,17 @@ function flowIssues(f) {
   return issues;
 }
 function parseRecord(input) {
+  const v = input?.schemaVersion;
+  if (typeof v === "number" && Number.isInteger(v) && v > SCHEMA_VERSION)
+    return {
+      ok: false,
+      issues: [
+        {
+          path: "schemaVersion",
+          message: `written by a newer Atticus (record version ${v}); install it to read this record`
+        }
+      ]
+    };
   const result = CatalogRecord.safeParse(input);
   if (!result.success) {
     return {
@@ -2551,7 +2608,7 @@ var Approver = z11.strictObject({
   groups: z11.array(z11.string().min(1)).default([]),
   people: z11.array(z11.string().min(1)).default([])
 }).refine((a) => a.roles.length + a.groups.length + a.people.length > 0, "name at least one role, group or person");
-var ROLES_SCHEMA_VERSION = 2;
+var ROLES_SCHEMA_VERSION = 3;
 var TeamPerson = z11.string().min(1).max(100).regex(/^@?[A-Za-z0-9][A-Za-z0-9._-]*$/, "a person's Git handle, such as pat or pat.doe");
 var Team = z11.strictObject({
   /** The id a repo manifest's `owner` names, e.g. team-ledger. */
@@ -2559,12 +2616,16 @@ var Team = z11.strictObject({
   /** What people call it, e.g. Ledger team. */
   name: z11.string().min(1).optional(),
   /** The Git handles of the people on it. */
-  people: z11.array(TeamPerson).default([])
+  people: z11.array(TeamPerson).default([]),
+  /** Version 3 (ADR 0191): who on the team takes each role on its repos' changes. */
+  roles: z11.record(RecordId, z11.array(TeamPerson).min(1)).optional()
 });
 var Roles = z11.strictObject({
-  schemaVersion: z11.union([V2, z11.literal(ROLES_SCHEMA_VERSION)]),
+  schemaVersion: z11.union([V2, z11.literal(2), z11.literal(ROLES_SCHEMA_VERSION)]),
   /** Version 2 (ADR 0140): the teams repos are owned by, and who is on each. */
   teams: z11.array(Team).default([]),
+  /** Version 3 (ADR 0191): the organisation's person for each role, when no team names one. */
+  defaults: z11.record(RecordId, z11.array(TeamPerson).min(1)).optional(),
   /** Extra roles; each is based on a built-in role's view. */
   custom: z11.array(z11.strictObject({ id: RecordId, name: z11.string().min(1), basedOn: z11.enum(BUILT_IN_ROLES) })).default([]),
   /** Optional roles this organisation uses. Core roles are always on. */
@@ -2581,12 +2642,31 @@ var Roles = z11.strictObject({
   const known = /* @__PURE__ */ new Set([...BUILT_IN_ROLES, ...r.custom.map((c) => c.id)]);
   unique(r.custom, (c) => c.id, ctx, "custom");
   unique(r.teams, (t) => t.id, ctx, "teams");
-  if (r.teams.length && r.schemaVersion < ROLES_SCHEMA_VERSION)
+  if (r.teams.length && r.schemaVersion < 2)
     ctx.addIssue({
       code: "custom",
       path: ["teams"],
       message: "teams needs schemaVersion 2: run atticus upgrade"
     });
+  const named = [
+    ...r.defaults ? [{ path: ["defaults"], roles: r.defaults }] : [],
+    ...r.teams.flatMap((t, i) => t.roles ? [{ path: ["teams", i, "roles"], roles: t.roles }] : [])
+  ];
+  for (const n of named) {
+    if (r.schemaVersion < ROLES_SCHEMA_VERSION)
+      ctx.addIssue({
+        code: "custom",
+        path: n.path,
+        message: "who takes each role needs schemaVersion 3: run atticus upgrade"
+      });
+    for (const role of Object.keys(n.roles))
+      if (!known.has(role))
+        ctx.addIssue({
+          code: "custom",
+          path: [...n.path, role],
+          message: `unknown role ${role}`
+        });
+  }
   r.custom.forEach((c, i) => {
     if (BUILT_IN_ROLES.includes(c.id)) {
       ctx.addIssue({
@@ -2771,6 +2851,27 @@ var IntegrationPattern = z11.strictObject({
   version: Semver,
   status: z11.enum(["confirmed", "to-review", "deprecated"])
 });
+function gitRefProblem(ref2) {
+  if (!ref2)
+    return "it is empty";
+  if (ref2.startsWith("-"))
+    return "it starts with -";
+  if (/[\x00-\x20\x7f]/.test(ref2))
+    return "it has a space or a control character";
+  if (/[~^:?*[\\]/.test(ref2))
+    return "it has one of ~ ^ : ? * [ \\";
+  if (ref2.includes(".."))
+    return "it has ..";
+  if (ref2.includes("@{") || ref2 === "@")
+    return "it is @ or has @{";
+  if (ref2.startsWith("/") || ref2.endsWith("/") || ref2.includes("//"))
+    return "it starts or ends with /, or has //";
+  if (ref2.endsWith("."))
+    return "it ends with .";
+  if (ref2.split("/").some((c) => c.startsWith(".") || c.endsWith(".lock")))
+    return "a part of it starts with . or ends with .lock";
+  return void 0;
+}
 var RelPath = z11.string().min(1).refine((p2) => !p2.startsWith("/") && !/^[A-Za-z]:/.test(p2) && !p2.includes("\\") && !p2.split("/").includes(".."), "a relative path inside the metarepo");
 var SourceTags = z11.strictObject({
   kinds: z11.array(RecordId).default([]),
@@ -2849,7 +2950,11 @@ var Sources = z11.strictObject({
     /** What the source is about (ADR 0083), to guide the knowledge scan and filter items. */
     tags: SourceTags.optional(),
     /** A git wiki's branch or tag; default its default branch. A name git takes as a ref, never as an option. */
-    ref: z11.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/, "a branch or tag name").optional(),
+    ref: z11.string().max(200).superRefine((r, ctx) => {
+      const why = gitRefProblem(r);
+      if (why)
+        ctx.addIssue({ code: "custom", message: `a branch or tag name: ${why}` });
+    }).optional(),
     /** The folder of a git wiki its pages are in; default the whole repository. */
     path: RelPath.optional(),
     /** A git wiki is cloned into local state (clone), or kept as a submodule of the metarepo under knowledge/repos/. */
@@ -2941,10 +3046,11 @@ var AdapterSettings = z11.record(z11.string(), z11.union([z11.string(), z11.numb
     }
   }
 });
-var adapter = (types, o = {}) => z11.strictObject({
-  type: z11.enum([...types, "mock", ...o.manual === false ? [] : ["manual"]]),
-  settings: AdapterSettings.default({})
-});
+var adapter = (types, o = {}) => {
+  const type = z11.enum([...types, "mock", ...o.manual === false ? [] : ["manual"]]);
+  const full = z11.strictObject({ type, settings: AdapterSettings.default({}) });
+  return z11.union([type.transform((t) => ({ type: t, settings: {} })), full]);
+};
 var BuildEngine = z11.enum(["speckit", "atticus"]);
 var Autonomy = z11.enum(["plan-only", "draft", "draft-and-pr"]);
 var RetrievalSettings = z11.strictObject({
@@ -3007,8 +3113,9 @@ var RuntimeFields = z11.strictObject({
    */
   modes: z11.strictObject({
     allowed: z11.array(ConfiguredMode).min(1),
-    default: ConfiguredMode
-  }).refine((m) => m.allowed.includes(m.default), "the default mode must be allowed").default({ allowed: ["hand-off"], default: "hand-off" }),
+    /** Left out: the first mode `allowed` lists (review round 50). */
+    default: ConfiguredMode.optional()
+  }).refine((m) => m.default === void 0 || m.allowed.includes(m.default), "the default mode must be allowed").transform((m) => ({ allowed: m.allowed, default: m.default ?? m.allowed[0] })).default({ allowed: ["hand-off"], default: "hand-off" }),
   models: z11.strictObject({
     allowed: z11.array(z11.string().min(1)).default([]),
     /** A recommended model per task type, shown in the assistant's picker hints. */
@@ -3336,6 +3443,9 @@ var Profile = z11.strictObject({
   });
 });
 
+// packages/core/dist/metarepo.js
+var LAYOUT_PATH = Sources.shape.layout.unwrap().shape.catalog.unwrap().optional();
+
 // packages/core/dist/roles-migrate.js
 import { isMap, parseDocument } from "yaml";
 
@@ -3745,6 +3855,13 @@ var AuditFile = z17.strictObject({
   items: z17.array(AuditItem)
 });
 
+// packages/core/dist/cite.js
+var SECRET_WORDS = "(?:password|passwd|pwd|secret|token|api[-_]?key|access[-_]?key|private[-_]?key|credentials?)";
+var KEY_LITERAL = new RegExp(`((?:^|[^A-Za-z0-9_.$-])[A-Za-z0-9_.$-]*?${SECRET_WORDS}["'\`]?\\]?(?:\\s*:\\s*[A-Za-z_][\\w.<>?\\[\\]]*(?=\\s*=))?\\s*(?::=|=>|=(?!=)|:(?!:))\\s*)(["'\`])((?:(?!\\2)[^\\\\]|\\\\.)+)\\2`, "i");
+var SETTER_LITERAL = new RegExp(`(\\b(?:set|with)[A-Za-z0-9_]*?${SECRET_WORDS}\\s*\\(\\s*)(["'\`])((?:(?!\\2)[^\\\\]|\\\\.)+)\\2`, "i");
+var KEY_BARE = new RegExp(`((?:\\bexport\\s+|--|[?&;])[A-Za-z0-9_.-]*?${SECRET_WORDS}\\s*=\\s*)([^\\s&;"'\`]+)`, "gi");
+var SECRET_IDENT = new RegExp(`[A-Za-z0-9_]*${SECRET_WORDS}[A-Za-z0-9_]*`, "i");
+
 // packages/core/dist/json-schema.js
 import { z as z27 } from "zod";
 
@@ -5332,7 +5449,7 @@ var DEFAULT_ROLES = Roles.parse({
   ]
 });
 var DEFAULT_RUNTIME = Runtime.parse({
-  schemaVersion: 2,
+  schemaVersion: RUNTIME_SCHEMA_VERSION,
   assistants: { allowed: ["copilot", "claude-code"], default: "copilot" }
 });
 var DEFAULT_SOURCES = Sources.parse({ schemaVersion: 1 });
@@ -5367,6 +5484,7 @@ import { parse as parse5 } from "yaml";
 
 // packages/core/dist/api.js
 import { z as z30 } from "zod";
+var NextStep = z30.object({ step: z30.literal("sync"), repos: z30.array(z30.string()) });
 var Problem = z30.object({
   type: z30.string(),
   title: z30.string(),
@@ -5375,7 +5493,9 @@ var Problem = z30.object({
   /** Field-level problems for 400s. */
   errors: z30.array(z30.object({ path: z30.string(), message: z30.string() })).optional(),
   /** For 403s on gated actions: who can act, e.g. "Needs an architect: R. Patel". */
-  needs: z30.object({ role: z30.string(), names: z30.array(z30.string()) }).optional()
+  needs: z30.object({ role: z30.string(), names: z30.array(z30.string()) }).optional(),
+  /** 3.9.0: what the app offers next, e.g. Sync the repos with no base clone here. */
+  next: NextStep.optional()
 });
 var Kind3 = z30.enum(RECORD_KINDS);
 var CatalogRecord2 = z30.union(RECORD_KINDS.map((k) => RECORD_SCHEMAS[k]));
@@ -5602,9 +5722,11 @@ var Coverage = z30.object({
 var JobState = z30.enum(["queued", "running", "done", "failed", "cancelled"]);
 var Job = z30.object({
   id: z30.string(),
-  kind: z30.enum(["scan", "sync", "reconcile", "index", "intake", "step", "local"]),
+  kind: z30.enum(["scan", "sync", "reconcile", "index", "intake", "step", "local", "work"]),
   state: JobState,
   progress: z30.object({ done: z30.number().int(), total: z30.number().int(), message: z30.string() }),
+  /** 3.1.0 (ADR 0187): what the job is, in words, for the Console. */
+  title: z30.string().optional(),
   startedAt: z30.string(),
   finishedAt: z30.string().optional(),
   errors: z30.array(z30.string()),
@@ -5649,7 +5771,12 @@ var ChangeSummary = z30.object({
   }),
   updatedAt: z30.string(),
   /** ADR 0113: it takes the fast path, one step from brief to tasks (its type is small, or its brief says so). */
-  fastPath: z30.boolean().optional()
+  fastPath: z30.boolean().optional(),
+  /**
+   * 3.9.0 (beta.23 review): the viewer's roles on the change, from its owners (any case, the
+   * words people write for a role, roles.yaml's custom roles); empty when it names them nowhere.
+   */
+  yourRoles: z30.array(QuestionRole).optional()
 });
 var ChangeDetail = ChangeSummary.extend({
   /** 2.66.0 (review round 35): what a hand-off said, such as a branch it couldn't push. */
@@ -5662,7 +5789,13 @@ var ChangeDetail = ChangeSummary.extend({
   handoff: z30.object({
     phase: Phase,
     pr: z30.string().optional(),
-    state: z30.enum(["none", "open", "merged", "closed"])
+    state: z30.enum(["none", "open", "merged", "closed"]),
+    /**
+     * 3.3.0 (app-only audit): the open hand-off's branch is here but not on the remote as it is
+     * here (its push failed); POST .../handoff/push is Push again. Absent once it is there.
+     */
+    unpushed: z30.boolean().optional(),
+    branch: z30.string().optional()
   }).optional()
 });
 var ArtifactContent = z30.object({
@@ -5718,7 +5851,16 @@ var Task = z30.object({
    * dependencies, and the earlier tasks of its own repo in tasks.md order); `sameRepo` names the
    * ones of its own repo. Absent when it waits for none, or once it is done.
    */
-  waits: z30.object({ tasks: z30.array(z30.string()), sameRepo: z30.array(z30.string()) }).optional()
+  waits: z30.object({ tasks: z30.array(z30.string()), sameRepo: z30.array(z30.string()) }).optional(),
+  /**
+   * 3.3.0 (app-only audit): the task branch has commits the change branch here hasn't, so its
+   * code isn't in the change yet (its PR raised and merged takes it in). Absent when it has none.
+   */
+  unmerged: z30.object({ commits: z30.number().int().positive(), branch: z30.string() }).optional(),
+  /** 3.3.0: a person decided the task's work isn't needed in the change, and why. */
+  decision: z30.object({ by: z30.string(), at: z30.string(), reason: z30.string() }).optional(),
+  /** 3.3.0: whether the task's repo has a build command now (repos.manifest.yaml). */
+  repoBuilds: z30.boolean().optional()
 });
 var RunView = RunSummary.extend({
   /**
@@ -5759,10 +5901,17 @@ var RunListItem = RunView.extend({
   toolCalls: z30.number().int().min(0).optional()
 });
 var StartStepRequest = z30.object({ args: z30.array(z30.string().min(1)).min(2) });
+var RunDoneRequest = z30.strictObject({ job: z30.boolean().optional() });
 var RunDoneView = RunView.extend({
   lines: z30.array(z30.string()).optional(),
-  next: z30.string().optional()
-});
+  next: z30.string().optional(),
+  /** 3.5.0 (ADR 0188): the repo a read's last batch put on the map (verify --write). */
+  applied: z30.string().optional()
+});
+var TaskContextView = z30.object({ markdown: z30.string() });
+var HistoryRecordingRequest = z30.object({ on: z30.boolean() });
+var HistoryRecordingView = z30.object({ on: z30.boolean() });
+var PruneRequest = z30.object({ change: z30.string().optional() });
 var PreparedStepView = z30.object({
   /** Left out when the step had nothing left to hand off: its lines say what it did. */
   runId: z30.string().optional(),
@@ -6123,7 +6272,20 @@ var ChangeKnowledgeItem = z30.object({
   tasks: z30.array(z30.string()).optional(),
   /** 2.30.0 (ADR 0132): the source of the page it is read from, and how much its word counts. */
   source: z30.string().optional(),
-  authority: z30.enum(SOURCE_AUTHORITIES).optional()
+  authority: z30.enum(SOURCE_AUTHORITIES).optional(),
+  /**
+   * 3.6.0 (ADR 0191): what it says, to open it in place: a section's own text with its page and
+   * heading, or an item's quote with its page. Left out when the page can't be read.
+   */
+  passage: z30.object({
+    source: z30.string(),
+    page: z30.string(),
+    path: z30.string(),
+    heading: z30.string(),
+    line: z30.number().int(),
+    text: z30.string(),
+    quote: z30.string().optional()
+  }).optional()
 });
 var KnowledgeConflictView = z30.object({
   /** The items it is about and its pages, each sorted: the same key is never asked twice. */
@@ -6623,6 +6785,117 @@ var StageCommentResult = z30.object({
   commit: z30.string(),
   next: z30.object({ command: z30.string(), slash: z30.string() })
 });
+var THREAD_STAGES = ["proposal", "feature", "architecture", "stories", "small"];
+var ThreadStage = z30.enum(THREAD_STAGES);
+var ThreadRunDetails = z30.object({
+  agent: z30.string(),
+  runtime: z30.string(),
+  promptPath: z30.string(),
+  output: z30.string().optional(),
+  promptTokens: z30.number().int().min(0).optional(),
+  model: z30.string().optional(),
+  attempt: z30.number().int().min(1)
+});
+var ThreadItem = z30.discriminatedUnion("kind", [
+  /** A prompt handed to the assistant (the stage's drafter, or the critic's lenses). */
+  z30.object({
+    kind: z30.literal("prompt"),
+    at: z30.string(),
+    runId: z30.string(),
+    who: z30.enum(["drafter", "critic"]),
+    prompt: z30.string(),
+    state: RunState,
+    details: ThreadRunDetails
+  }),
+  /** What came back, and what its checks said. */
+  z30.object({
+    kind: z30.literal("answer"),
+    at: z30.string(),
+    runId: z30.string(),
+    who: z30.enum(["drafter", "critic"]),
+    /** passed: the checks read it; failed: they found problems (listed); checking: not yet. */
+    checked: z30.enum(["passed", "failed", "checking"]),
+    /** Who checked it: the app when the file arrived (ADR 0189), or a person's Done. */
+    by: z30.enum(["app", "person"]).optional(),
+    summary: z30.array(z30.string()),
+    problems: z30.array(z30.string())
+  }),
+  /** The files the stage wrote from an answer. */
+  z30.object({ kind: z30.literal("changed"), at: z30.string(), files: z30.array(z30.string()) }),
+  z30.object({
+    kind: z30.literal("finding"),
+    at: z30.string(),
+    view: StageFindingView,
+    /**
+     * Whether the stage's assistant writes the file the finding cites: Fix then goes to it in the
+     * next round; otherwise Fix opens the file at its line in the app's editor (`edit`).
+     */
+    assistantWrites: z30.boolean(),
+    edit: z30.object({
+      artifact: z30.string(),
+      file: z30.string().optional(),
+      line: z30.number().int().optional()
+    }).optional()
+  }),
+  z30.object({ kind: z30.literal("question"), at: z30.string(), question: Question }),
+  z30.object({
+    kind: z30.literal("reply"),
+    at: z30.string(),
+    text: z30.string(),
+    by: z30.string(),
+    /** A round of the stage has read it. */
+    read: z30.boolean(),
+    /** The finding it is about, for a comment on one. */
+    about: z30.string().optional()
+  }),
+  z30.object({
+    kind: z30.literal("correction"),
+    at: z30.string(),
+    text: z30.string(),
+    label: z30.string(),
+    by: z30.string(),
+    state: z30.string()
+  }),
+  /** A question the assistant raised that couldn't be kept: its evidence was no line. */
+  z30.object({
+    kind: z30.literal("dropped"),
+    at: z30.string(),
+    key: z30.string(),
+    question: z30.string(),
+    evidence: z30.array(z30.string()),
+    nearest: z30.string().optional()
+  }),
+  z30.object({ kind: z30.literal("note"), at: z30.string(), text: z30.string() })
+]);
+var StageThreadView = z30.object({
+  change: z30.string(),
+  stage: ThreadStage,
+  /** Where the stage is, in one word, and the one sentence the thread opens with. */
+  state: z30.enum(["not-started", "waiting", "questions", "drafting", "stopped", "done"]),
+  headline: z30.string(),
+  items: z30.array(ThreadItem),
+  /** The run waiting for the assistant's answer, if one does. */
+  waiting: z30.object({ runId: z30.string(), prompt: z30.string() }).optional(),
+  /** The step's words, for POST /api/runs/handoff (the next round's prompt). */
+  step: z30.array(z30.string()),
+  /** Whether a reply is taken now, and if not, why. */
+  reply: z30.object({ open: z30.boolean(), why: z30.string().optional() }),
+  problems: z30.array(z30.object({ file: z30.string(), message: z30.string() }))
+});
+var StageThreadPost = z30.discriminatedUnion("kind", [
+  z30.strictObject({ kind: z30.literal("reply"), text: z30.string().trim().min(1).max(4e3) }),
+  z30.strictObject({
+    kind: z30.literal("finding"),
+    finding: z30.string().min(1),
+    gate: z30.string().optional(),
+    text: z30.string().trim().min(1).max(4e3)
+  }),
+  z30.strictObject({ kind: z30.literal("keep"), key: z30.string().regex(/^[0-9a-f]{12}$/) })
+]);
+var StageThreadPostResult = z30.object({
+  files: z30.array(z30.string()),
+  thread: StageThreadView
+});
 var DRAFT_PAGES = ["feature", "architecture", "stories", "tasks"];
 var DraftPage = z30.enum(DRAFT_PAGES);
 var DraftProvenance = z30.object({
@@ -7060,14 +7333,25 @@ var Health = z30.object({
   openspec: z30.string().optional(),
   user: z30.string(),
   /** 2.22.0: started with `atticus ui --full`, so the app offers every page, not only the six. */
-  full: z30.boolean().optional()
+  full: z30.boolean().optional(),
+  /**
+   * 3.5.0 (ADR 0190): whether the folder the app runs in is a metarepo (org-pack/, or
+   * .atticus/org-pack/). When it isn't, the app offers Create the metarepo here.
+   */
+  metarepo: z30.boolean().optional()
 });
 var ScanRequest = z30.strictObject({
   repos: z30.array(RecordId).optional(),
   /** Ignore the cache and rescan everything. */
   full: z30.boolean().default(false),
   /** Another branch, scanned beside the baseline into catalog/branches/<branch>/ (ADR 0123). */
-  ref: GitRef.optional()
+  ref: GitRef.optional(),
+  /**
+   * 3.3.0 (app-only audit): the app's scan is a cross-check with the built-in readers, and asks
+   * which repo answers on an unknown host only for the repos the assistant has read (facts on
+   * file); `askAll` asks for every repo, as the command line's `atticus scan` does.
+   */
+  askAll: z30.boolean().optional()
 });
 var RepoBranchesView = z30.object({
   id: RecordId,
@@ -7155,6 +7439,8 @@ var ChangeCockpit = z30.object({
    */
   openQuestionsByRole: z30.partialRecord(QuestionRole, z30.number().int()).optional(),
   yourRoles: z30.array(QuestionRole).optional(),
+  /** 3.6.0 (ADR 0191): who the change waits on now, by role and name. */
+  waitsOn: z30.lazy(() => WaitsOn).optional(),
   repos: z30.array(z30.object({ id: z30.string(), branch: z30.string(), base: z30.string(), pr: z30.string().optional() }))
 });
 var NewChangeRequest = z30.strictObject({
@@ -7205,13 +7491,48 @@ var ProposePlanView = z30.object({
    */
   applyFirst: z30.array(z30.string()).optional()
 });
+var CONFIRMED_WRITES = [
+  "handoff",
+  "release-prs",
+  "merge",
+  "task-pr",
+  "digest-send",
+  "propose",
+  "step-run",
+  "ai-model",
+  "ai-test",
+  // 3.6.0 (ADR 0191): the plan's work items in a live work tracker, and an owner question sent.
+  "work-items",
+  "owner-ask"
+];
+var ConfirmedWrite = z30.enum(CONFIRMED_WRITES);
+var Confirmation = z30.string().regex(/^[A-Za-z0-9_-]{16,128}$/, "a confirmation");
+var ConfirmationRequest = z30.strictObject({
+  write: ConfirmedWrite,
+  /**
+   * What the write is for: the change, `<change>/<task>`, the step, the scope, the digest's
+   * channel (3.1.0; `me` before) or `model`.
+   */
+  target: z30.string().min(1).max(400),
+  /** The page's own key, from its <meta name="atticus-page-key">; never printed. */
+  pageKey: z30.string().max(200).optional()
+});
+var ConfirmationView = z30.object({
+  confirmation: Confirmation,
+  write: ConfirmedWrite,
+  target: z30.string(),
+  expiresAt: z30.string()
+});
+var ConfirmedRequest = z30.strictObject({ confirmation: Confirmation.optional() });
 var ProposeRequest = z30.strictObject({
   scope: ProposeScope,
   /** Exactly the files the person saw listed; one that changed back since is left out. */
   files: z30.array(z30.string().min(1)).min(1),
   title: z30.string().max(200).optional(),
   /** The branch GET's plan showed, so the PR is on the branch the person saw. */
-  branch: z30.string().max(200).optional()
+  branch: z30.string().max(200).optional(),
+  /** 3.0.0 (ADR 0186): the person's confirmation from the app (`propose`, the scope). */
+  confirmation: Confirmation.optional()
 });
 var LinesView = z30.object({
   code: z30.number().int().optional(),
@@ -7446,11 +7767,30 @@ var FindingActionRequest = z30.strictObject({
 var OpenWorkspaceRequest = z30.strictObject({ repos: z30.array(RecordId).min(1) });
 var HandoffRequest = z30.strictObject({
   phase: Phase.optional(),
-  repo: z30.string().optional()
+  repo: z30.string().optional(),
+  /** 3.0.0 (ADR 0186): the person's confirmation from the app (`handoff`, the change). */
+  confirmation: Confirmation.optional()
+});
+var SyncRequest = z30.strictObject({
+  repo: z30.string().optional(),
+  confirmation: Confirmation.optional()
+});
+var ReleasePrsRequest = z30.strictObject({ confirmation: Confirmation.optional() });
+var TaskDoneRequest = z30.strictObject({
+  done: z30.boolean(),
+  /**
+   * 3.3.0 (app-only audit): why the task's work isn't needed, when its branch has commits the
+   * change branch hasn't (else marking it done is 409); recorded with the person's name.
+   */
+  reason: z30.string().max(2e3).optional()
+});
+var UpstreamRequest = z30.strictObject({
+  upstream: z30.string().regex(/^[A-Za-z0-9][\w.-]*\/[\w./-]+$/, "a remote branch, such as origin/main")
+});
+var TaskBuildRequest = z30.strictObject({
+  raise: z30.boolean().optional(),
+  confirmation: Confirmation.optional()
 });
-var SyncRequest = z30.strictObject({ repo: z30.string().optional() });
-var ReleasePrsRequest = z30.strictObject({});
-var TaskDoneRequest = z30.strictObject({ done: z30.boolean() });
 var CHANGE_OWNER_ROLES = [
   "product-owner",
   "architect",
@@ -7507,7 +7847,9 @@ var StepRunRequest = z30.strictObject({
   with: z30.string().min(1),
   inputsSha256: z30.string().regex(/^[0-9a-f]{64}$/, "the sha-256 the preview showed"),
   fillOnly: z30.boolean().optional(),
-  change: z30.string().optional()
+  change: z30.string().optional(),
+  /** 3.0.0 (ADR 0186): the person's confirmation from the app (`step-run`, the step). */
+  confirmation: Confirmation.optional()
 });
 var ArchiveRequest = z30.strictObject({ rescan: z30.boolean().optional() });
 var DraftRequestsRequest = z30.strictObject({ force: z30.boolean().optional() });
@@ -7550,7 +7892,10 @@ var SaveNotifyRequest = z30.strictObject({
   digest: z30.enum(["off", "daily", "weekly"]),
   channel: z30.string().trim().min(1).optional()
 });
-var SendDigestRequest = z30.strictObject({ send: z30.boolean().default(false) });
+var SendDigestRequest = z30.strictObject({
+  send: z30.boolean().default(false),
+  confirmation: Confirmation.optional()
+});
 var TriageDecideRequest = z30.strictObject({
   option: z30.number().int().min(1),
   reason: z30.string().trim().min(1).optional()
@@ -7586,7 +7931,8 @@ var QuestionList = z30.object({
   problems: z30.array(z30.object({ file: z30.string(), message: z30.string() })),
   /**
    * 2.51.0: every question on file by state, whatever `state` or `mine` the list asked for, so a
-   * page shows its counts from the one request.
+   * page shows its counts from the one request. With `change` they are that change's; with `role`
+   * that role's, as the list is (`byRole` stays every role's).
    */
   counts: z30.object({
     open: z30.number().int(),
@@ -7630,6 +7976,8 @@ var QuestionList = z30.object({
      * the stage's that asked. Left out for a question no change's phase raised.
      */
     role: QuestionRole.optional(),
+    /** 3.6.0 (ADR 0191): what it asks (business, design, delivery), its own or its role's. */
+    asks: QuestionAsks.optional(),
     /**
      * 2.36.0 (ADR 0144, Q5): the answer the assistant proposed, for an open question, when
      * every line it cites says what it quotes. A person accepts it or answers otherwise.
@@ -8288,6 +8636,159 @@ var UpgradeView = z30.object({
   stamp: z30.string().optional(),
   pending: z30.array(z30.object({ id: z30.string(), summary: z30.string(), files: z30.array(z30.string()) }))
 });
+var FileEditView = z30.object({
+  path: z30.string(),
+  changes: z30.array(z30.object({ was: z30.string().optional(), now: z30.string().optional() })),
+  written: z30.boolean(),
+  note: z30.string(),
+  /** The raw editor's runtime.yaml edit moves where the model's key goes: the write needs `ai-model`. */
+  confirm: z30.literal("ai-model").optional()
+});
+var SetupMetarepoView = z30.object({
+  metarepo: z30.boolean(),
+  root: z30.string(),
+  folder: z30.string(),
+  suggested: z30.object({ name: z30.string(), platform: z30.string() }),
+  /** The folder's origin, when it is a clone (without credentials). */
+  origin: z30.string().optional(),
+  /** The metarepo's id on the Git host, read from origin. */
+  metarepoId: z30.string().optional()
+});
+var CreateMetarepoRequest = z30.strictObject({
+  name: RecordId,
+  platform: RecordId,
+  owner: z30.string().trim().min(1).max(100).optional(),
+  /** The metarepo's repo on the Git host, written under runtime.yaml's manual Git host. */
+  metarepo: z30.string().trim().min(1).max(300).optional()
+});
+var OpenFolderRequest = z30.strictObject({ path: z30.string().min(1).max(4096) });
+var OpenFolderView = z30.object({
+  url: z30.string(),
+  root: z30.string(),
+  metarepo: z30.boolean()
+});
+var ReposPlanRequest = z30.strictObject({
+  urls: z30.string().max(2e5).optional(),
+  dir: z30.string().min(1).max(4096).optional(),
+  platform: RecordId.optional()
+}).refine((b) => !!b.urls?.trim() !== !!b.dir, "send urls or dir, one of them");
+var PlannedRepoView = z30.object({
+  id: z30.string(),
+  url: z30.string(),
+  /** What the person gave, when the URL was normalised from it. */
+  given: z30.string().optional(),
+  type: z30.string(),
+  defaultBranch: z30.string().optional(),
+  /** The id it would have had, and why it got another (`-2`). */
+  renamed: z30.object({ from: z30.string(), why: z30.string() }).optional(),
+  detected: z30.object({ signals: z30.array(z30.string()), confidence: z30.string() }).optional()
+});
+var ReposPlanView = z30.object({
+  platform: z30.string().optional(),
+  platforms: z30.array(z30.string()),
+  repos: z30.array(PlannedRepoView),
+  /** Given, but a manifest lists that clone URL already: left out. */
+  listed: z30.array(z30.object({ url: z30.string(), id: z30.string() })),
+  refused: z30.array(z30.object({ given: z30.string(), why: z30.string() })),
+  /** Folders repos discover looked at that aren't repos. */
+  skipped: z30.array(z30.object({ path: z30.string(), reason: z30.string() }))
+});
+var AddReposRequest = z30.strictObject({
+  platform: RecordId.optional(),
+  repos: z30.array(z30.strictObject({
+    id: RecordId,
+    url: z30.string().min(1).max(2e3),
+    type: z30.string().max(100).optional(),
+    owner: z30.string().max(100).optional(),
+    defaultBranch: z30.string().max(250).optional(),
+    /** What it is, in the person's words (ADR 0128); optional. */
+    description: z30.string().max(300).optional()
+  })).min(1).max(500),
+  preview: z30.boolean().optional()
+});
+var RepoTypeDetectView = z30.object({
+  repo: z30.string(),
+  /** The org pack's repo types (atticus repo-type detect), or the files as repo add reads them. */
+  from: z30.enum(["repo-types", "files"]),
+  verdict: z30.string(),
+  /** The type to write, when the match settles one. */
+  type: z30.string().optional(),
+  signals: z30.array(z30.string()).optional(),
+  confidence: z30.string().optional(),
+  matches: z30.array(z30.object({ type: z30.string(), name: z30.string(), score: z30.number() }))
+});
+var RepoTypeRequest = z30.strictObject({
+  type: z30.string().trim().min(1).max(100),
+  preview: z30.boolean().optional()
+});
+var AdapterSettingValue = z30.union([z30.string(), z30.number(), z30.boolean(), z30.array(z30.string())]);
+var AdaptersView = z30.object({
+  /** runtime.yaml, metarepo-relative. */
+  path: z30.string(),
+  /** 3.9.0: runtime.yaml's sha256 as read, sent back as a write's `baseSha256`. */
+  sha256: z30.string(),
+  kinds: z30.array(z30.object({
+    kind: z30.string(),
+    types: z30.array(z30.string()),
+    /** The settings Atticus reads for this kind; a plugin may read more. */
+    fields: z30.array(z30.object({ name: z30.string(), list: z30.boolean() })),
+    current: z30.object({ type: z30.string(), settings: z30.record(z30.string(), AdapterSettingValue) }).nullable()
+  })),
+  problems: z30.array(z30.string())
+});
+var AdapterRequest = z30.strictObject({
+  /** The adapter, or null to take it out of runtime.yaml. */
+  value: z30.strictObject({
+    type: z30.string().min(1).max(100),
+    settings: z30.record(z30.string().max(100), AdapterSettingValue).optional()
+  }).nullable(),
+  /**
+   * 3.9.0: runtime.yaml's sha256 as the form read it (AdaptersView's), so a write onto a file
+   * changed since is refused (409), never overwriting the newer edit.
+   */
+  baseSha256: z30.string().regex(/^[0-9a-f]{64}$/).optional(),
+  preview: z30.boolean().optional()
+});
+var OrgPackFileView = z30.object({
+  path: z30.string(),
+  /** Relative to the org pack folder. */
+  rel: z30.string(),
+  content: z30.string(),
+  sha256: z30.string(),
+  exists: z30.boolean(),
+  /** Checked with its schema before it is written (a YAML file Atticus reads). */
+  checked: z30.boolean()
+});
+var OrgPackFileRequest = z30.strictObject({
+  path: z30.string().min(1).max(500),
+  content: z30.string().max(2e6),
+  /** The file's sha256 as opened (GET's), so an edit made meanwhile is refused. */
+  baseSha256: z30.string().regex(/^[0-9a-f]{64}$/),
+  preview: z30.boolean().optional(),
+  confirmation: Confirmation.optional()
+});
+var PatternRequest = z30.strictObject({
+  code: z30.string().min(1).max(60),
+  name: z30.string().min(1).max(200),
+  definition: z30.string().min(1).max(2e3),
+  interaction: z30.string(),
+  route: z30.string(),
+  targetType: z30.string(),
+  controls: z30.array(z30.string().max(200)).max(50).optional(),
+  source: z30.string().min(1).max(500),
+  version: z30.string().max(40).optional(),
+  status: z30.string().optional(),
+  preview: z30.boolean().optional()
+});
+var SourceRequest = z30.strictObject({
+  type: z30.string().min(1).max(40),
+  location: z30.string().min(1).max(2e3),
+  id: RecordId.optional(),
+  /** A git wiki's folder of pages, and its branch or tag. */
+  path: z30.string().max(500).optional(),
+  ref: z30.string().max(250).optional(),
+  preview: z30.boolean().optional()
+});
 var ConnectLinksRequest = z30.object({
   from: z30.string().min(1),
   to: LinkBox,
@@ -8356,7 +8857,7 @@ var FileChangeResult = z30.object({
   commit: z30.string()
 });
 var SketchStrokeRequest = z30.object({
-  stroke: z30.object({ kind: z30.enum(["call", "topic", "table", "remove", "retarget", "undo"]) }).passthrough(),
+  stroke: z30.object({ kind: z30.enum(["call", "topic", "table", "remove", "retarget", "undo", "retire"]) }).passthrough(),
   /** Say what it would write; write nothing. */
   preview: z30.boolean().optional(),
   /** The preview's fingerprint of the target flows: the write is refused (409) when they changed since. */
@@ -8538,8 +9039,102 @@ var CopilotRunCurrent = z30.object({
   why: z30.string().optional(),
   model: z30.string().optional()
 });
+var ActivityKind = z30.enum([
+  // The app's own jobs (ADR 0015), by their kind.
+  "scan",
+  "sync",
+  "reconcile",
+  "index",
+  "intake",
+  "step",
+  "local",
+  /** A request the page waits on, run as a job (the critic, a wiki's sync, a step run, Done). */
+  "work",
+  /** An unattended Copilot run the app started (ADR 0173): its lines are its tabs. */
+  "copilot",
+  /** A command run in a terminal, by an editor or by a Copilot session. */
+  "command",
+  /** A hand-off run waiting for the person's assistant, and its Done. */
+  "handoff"
+]);
+var ActivityState = z30.enum([
+  "running",
+  "waiting",
+  "done",
+  "failed",
+  "cancelled",
+  /** Its process is gone and it never said how it ended (a terminal closed, a crash). */
+  "ended"
+]);
+var ActivityWhere = z30.enum([
+  "app",
+  "terminal",
+  "vscode",
+  "intellij",
+  "copilot",
+  /** A hand-off run: the person's own assistant does the work. */
+  "assistant"
+]);
+var ActivityEntry = z30.object({
+  /** A job's id (job-N), a Copilot run's (copilot-run-...), term-<runId> for a command, a hand-off run's (run-...). */
+  id: z30.string().min(1),
+  kind: ActivityKind,
+  /** What it is, in its own words: the command (`atticus map forge-ledger`), or the app's job. Left out for a job that gave none: the page names it by its kind. */
+  title: z30.string().optional(),
+  where: ActivityWhere,
+  state: ActivityState,
+  startedAt: z30.string(),
+  finishedAt: z30.string().optional(),
+  /** How far it is, when it says (a job's progress). */
+  progress: z30.object({ done: z30.number().int(), total: z30.number().int(), message: z30.string() }).optional(),
+  exitCode: z30.number().int().optional(),
+  /** How many lines it has printed: the page asks for the ones it hasn't. */
+  lines: z30.number().int().min(0),
+  /** The first line still kept (older ones are dropped past the cap). */
+  from: z30.number().int().min(0),
+  /**
+   * 3.9.0 (review of beta.23): which version of its lines these are, for an entry whose lines
+   * are rewritten rather than only added to (a hand-off run's say what to do, then what Done
+   * did). When it changes, the page reads its lines again from the start instead of adding.
+   */
+  rev: z30.string().optional(),
+  /** The route that stops it (POST), when the app can; a command stops in its terminal. */
+  stop: z30.string().optional(),
+  jobId: z30.string().optional(),
+  copilotRunId: z30.string().optional(),
+  /** A command's run id (its files in .atticus/logs/). */
+  runId: z30.string().optional(),
+  /** A hand-off run: its change, where its prompt is and where the answer goes. */
+  handoff: z30.object({
+    runId: z30.string(),
+    change: z30.string(),
+    agent: z30.string().optional(),
+    promptPath: z30.string(),
+    output: z30.string().optional()
+  }).optional()
+});
+var ActivityList = z30.object({
+  /** Newest first. */
+  entries: z30.array(ActivityEntry),
+  /** How many are running now. */
+  running: z30.number().int().min(0)
+});
+var ActivityLines = z30.object({
+  id: z30.string(),
+  /** The number of the first of these lines. */
+  from: z30.number().int().min(0),
+  lines: z30.array(z30.string()),
+  /** How many lines it has printed in all. */
+  total: z30.number().int().min(0),
+  state: ActivityState
+});
 var LiveEvent = z30.discriminatedUnion("type", [
-  z30.object({ type: z30.literal("file.changed"), path: z30.string() }),
+  z30.object({
+    type: z30.literal("file.changed"),
+    path: z30.string(),
+    /** 3.9.0: whether it can change the catalog, by the folders the org pack's layout names. */
+    catalog: z30.boolean().optional()
+  }),
   z30.object({
     type: z30.literal("job.progress"),
     jobId: z30.string(),
@@ -8560,8 +9155,147 @@ var LiveEvent = z30.discriminatedUnion("type", [
     /** The number of the first of these lines in the tab. */
     at: z30.number().int().min(0),
     lines: z30.array(z30.string())
+  }),
+  // ADR 0187: an activity appeared or changed, and new lines one printed.
+  z30.object({ type: z30.literal("activity.changed"), entry: ActivityEntry }),
+  z30.object({
+    type: z30.literal("activity.lines"),
+    id: z30.string(),
+    /** The number of the first of these lines. */
+    at: z30.number().int().min(0),
+    lines: z30.array(z30.string())
   })
 ]);
+var RouteQuestionRequest = z30.strictObject({ role: QuestionRole });
+var OwnerSuggestion = z30.object({
+  role: z30.string(),
+  people: z30.array(z30.string()),
+  from: z30.union([
+    z30.object({ team: z30.string(), name: z30.string().optional(), repos: z30.array(z30.string()) }),
+    z30.object({ default: z30.literal(true) })
+  ])
+});
+var OwnerSuggestionList = z30.object({
+  change: z30.string(),
+  suggestions: z30.array(OwnerSuggestion),
+  /** Why there are none, in words, when there are none. */
+  note: z30.string().optional()
+});
+var WaitsOn = z30.object({
+  /** The change.yaml owner key: product-owner, architect, business-analyst or team-lead. */
+  role: z30.string(),
+  people: z30.array(z30.string()),
+  /** `handoff`: its hand-off PR waits on their review; `phase`: the phase's work is theirs. */
+  because: z30.enum(["handoff", "phase"]),
+  phase: z30.string()
+});
+var FindingView = z30.strictObject({ ...Finding.shape, asks: QuestionAsks });
+var WorkItemPlan = z30.object({
+  change: z30.string(),
+  /** none: runtime.yaml names no work tracker; manual: steps for a person; live: the tracker. */
+  tracker: z30.enum(["none", "manual", "live"]),
+  items: z30.array(z30.object({
+    key: z30.string(),
+    type: z30.string(),
+    title: z30.string(),
+    action: z30.enum(["create", "update", "unchanged", "orphaned"]),
+    /** The tracker's id once known; `manual:<step>` until a person records it. */
+    id: z30.string().optional(),
+    /** The step to record it on, for a manual id. */
+    step: z30.string().optional(),
+    /** The story it is under, for a task; the story's own key for a story. */
+    story: z30.string().optional()
+  })),
+  /** The command that does the same in a terminal. */
+  command: z30.string()
+});
+var WorkItemSyncRequest = z30.strictObject({
+  confirmation: Confirmation.optional(),
+  /** 3.9.0: run the sync as a job (202 and its id; the job's result `answer` is the result). */
+  job: z30.boolean().optional()
+});
+var WorkItemSyncResult = z30.object({
+  plan: WorkItemPlan,
+  lines: z30.array(z30.string()),
+  done: z30.array(z30.object({ key: z30.string(), action: z30.string(), id: z30.string() })),
+  failed: z30.array(z30.object({ key: z30.string(), reason: z30.string() }))
+});
+var SendOwnerAskRequest = z30.strictObject({ confirmation: Confirmation.optional() });
+var SentOwnerAsk = z30.object({
+  /** sent: through the adapter; step: a manual step for a person; not-sent: why in `why`. */
+  state: z30.enum(["sent", "step", "not-sent"]),
+  to: z30.string(),
+  id: z30.string().optional(),
+  why: z30.string().optional()
+});
+var KnowledgePassageView = z30.object({
+  source: z30.string(),
+  page: z30.string(),
+  /** The page's root-relative path (the snapshot copy, or the inputs/ file). */
+  path: z30.string(),
+  heading: z30.string(),
+  line: z30.number().int(),
+  text: z30.string()
+});
+var KnowledgeAnswerView = z30.object({
+  items: z30.array(z30.object({
+    id: z30.string(),
+    kind: z30.string(),
+    title: z30.string(),
+    quote: z30.object({
+      source: z30.string(),
+      page: z30.string(),
+      section: z30.string().optional(),
+      text: z30.string()
+    }).optional()
+  })),
+  passages: z30.array(KnowledgePassageView),
+  /** The AI step that answers from the items in words, citing them (atticus knowledge ask). */
+  command: z30.string()
+});
+var StoryShapeOp = z30.enum(["rename", "split", "merge", "add"]);
+var StoryShapeRequest = z30.strictObject({
+  op: StoryShapeOp,
+  /** rename, split: the story; merge: the stories, the first keeps its number. */
+  story: z30.string().optional(),
+  stories: z30.array(z30.string()).min(2).optional(),
+  /** rename, merge, add: its name; split: the first part's. */
+  name: z30.string().trim().min(1).max(200),
+  /** What the story is for, in the person's words (add, a split's parts). */
+  words: z30.string().trim().max(2e3).optional(),
+  /** split: the other parts, each a story of its own. */
+  parts: z30.array(z30.strictObject({
+    name: z30.string().trim().min(1).max(200),
+    words: z30.string().trim().max(2e3).optional()
+  })).optional()
+});
+var StoryShapeEntryView = z30.object({
+  id: z30.string(),
+  op: StoryShapeOp,
+  story: z30.string().optional(),
+  stories: z30.array(z30.string()).optional(),
+  name: z30.string(),
+  words: z30.string().optional(),
+  parts: z30.array(z30.object({ id: z30.string(), name: z30.string(), words: z30.string().optional() })).optional(),
+  /** The story an added one is. */
+  added: z30.string().optional(),
+  by: z30.string(),
+  at: z30.string(),
+  /** waiting: no draft has read it yet; applied: the stories now have it, with the run. */
+  state: z30.enum(["waiting", "applied"]),
+  run: z30.string().optional()
+});
+var StoryShapeView = z30.object({
+  change: z30.string(),
+  file: z30.string(),
+  entries: z30.array(StoryShapeEntryView),
+  /** Each task's story as the last draft mapped it, by task id. */
+  assigned: z30.record(z30.string(), z30.string()),
+  /** What the coverage check found: a story with no task, a task with no story. */
+  uncovered: z30.array(z30.string()),
+  /** The step that maps the tasks to the stories again. */
+  command: z30.string()
+});
 var str3 = { type: "string" };
 var ref = (name) => ({ $ref: `#/components/schemas/${name}` });
 var arrayOf = (name) => ({ type: "array", items: ref(name) });
@@ -8592,10 +9326,20 @@ var OPS = {
       ok: { status: 200, schema: "Health", description: "OK" }
     }
   },
+  "/api/confirmations": {
+    post: {
+      id: "confirmWrite",
+      summary: "3.0.0 (ADR 0186): the app's page asks, on the person's click, for a confirmation of one write to a shared system (a hand-off, the release PRs, a merge, a task's PR, sending the digest, Propose for review, a step run with a team's tool, where the model's key goes, a Test of uncommitted model settings). It needs the page key the server puts in the page and never prints, so the session token alone gets 403; the confirmation is for that write and target, used once, and expires after two minutes",
+      tag: "system",
+      body: ConfirmationRequest,
+      ok: { status: 201, schema: "ConfirmationView", description: "The confirmation" },
+      errors: [400, 403]
+    }
+  },
   "/api/me": {
     get: {
       id: "getMe",
-      summary: "Who is using the app: the metarepo's Git user (handle, name, email, and a warning when the OS user stood in), what AI may do and the digest settings (ADR 0073)",
+      summary: "Who is using the app: the metarepo's Git user (handle, name, email, and a warning when the OS user stood in), what AI may do and the digest settings (ADR 0073); 3.1.0: notify.to, where Send it to me posts",
       tag: "system",
       ok: {
         status: 200,
@@ -8627,7 +9371,7 @@ var OPS = {
   "/api/me/digest": {
     post: {
       id: "sendDigest",
-      summary: "What waits on the person; with send, posted through the notify adapter as their approval",
+      summary: "What waits on the person; with send, posted through the notify adapter as their approval. 3.0.0 (ADR 0186): send needs the person's confirmation, else 403. 3.1.0 (review round 50): its target is the channel it posts to (GET /api/me's notify.to, read again at the send), not `me`",
       tag: "system",
       body: SendDigestRequest,
       ok: {
@@ -8635,7 +9379,7 @@ var OPS = {
         schema: { type: "object", required: ["title", "body", "lines"] },
         description: "The digest, with sent or notSent"
       },
-      errors: [400]
+      errors: [400, 403]
     }
   },
   "/api/across": {
@@ -8775,8 +9519,11 @@ var OPS = {
   "/api/setup": {
     get: {
       id: "getSetup",
-      summary: "The setup checklist until the catalog is accepted, with a plain fix for each step",
+      summary: "The setup checklist until the catalog is accepted, with a plain fix for each step; the machine step says `checking` while the machine's checks run",
       tag: "system",
+      params: [
+        q("machine", { type: "string", enum: ["wait"] }, "Wait for the machine's checks instead of answering with the machine step checking")
+      ],
       ok: {
         status: 200,
         schema: { type: "object", required: ["steps", "baselined"] },
@@ -8969,7 +9716,7 @@ var OPS = {
   "/api/ask": {
     get: {
       id: "ask",
-      summary: "Answer a plain-language question from the catalog; the query used is always returned",
+      summary: "Answer a plain-language question from the catalog; the query used is always returned. 3.6.0 (ADR 0191): `knowledge` (KnowledgeAnswerView) says what the organisation's knowledge items, wiki snapshots and inputs/ files say to it, each cited",
       tag: "catalog",
       params: [q("q", str3, "The question, e.g. who calls ledger-api?")],
       ok: {
@@ -9422,10 +10169,11 @@ var OPS = {
   "/api/workspace/sync": {
     post: {
       id: "syncWorkspace",
-      summary: "Clone or update base clones",
+      summary: "Clone or update base clones. 3.0.0 (review round 48): 409 while a sync runs on this server",
       tag: "workspace",
       body: ScanRequest.pick({ repos: true }),
-      ok: { status: 202, schema: "JobAccepted", description: "Job started" }
+      ok: { status: 202, schema: "JobAccepted", description: "Job started" },
+      errors: [409]
     }
   },
   "/api/scan": {
@@ -9441,11 +10189,11 @@ var OPS = {
   "/api/reconcile": {
     post: {
       id: "startReconcile",
-      summary: "Check a diagram against the catalog",
+      summary: "Check a diagram against the catalog. 3.0.0 (review round 48): 409 while a reconcile runs on this server",
       tag: "scans",
       body: ReconcileRequest,
       ok: { status: 202, schema: "JobAccepted", description: "Job started" },
-      errors: [404]
+      errors: [404, 409]
     }
   },
   "/api/jobs/{jobId}": {
@@ -9513,7 +10261,7 @@ var OPS = {
     },
     post: {
       id: "proposeForReview",
-      summary: "2.65.0 (ADR 0183): on the person's yes, commit exactly those files to the branch, push it and open the PR; a person merges",
+      summary: "2.65.0 (ADR 0183): on the person's yes, commit exactly those files to the branch, push it and open the PR; a person merges. 3.0.0 (ADR 0186): needs the person's confirmation (`propose`, the scope), else 403",
       tag: "workspace",
       body: ProposeRequest,
       ok: {
@@ -9522,7 +10270,7 @@ var OPS = {
         description: "Started: its job's result is the code and the lines"
       },
       // 2.68.0: 409 while another local step (Apply, Propose, Bring in) runs.
-      errors: [400, 409]
+      errors: [400, 403, 409]
     }
   },
   "/api/owner-questions": {
@@ -9533,6 +10281,17 @@ var OPS = {
       ok: { status: 200, schema: "OwnerQuestionList", description: "OK" }
     }
   },
+  "/api/owner-questions/{id}/send": {
+    post: {
+      id: "sendOwnerQuestion",
+      summary: "3.6.0 (ADR 0191): send the owner question through the notify adapter to its owner, on the person's `owner-ask` confirmation; with manual notifications it is a step for a person, and with none it says to copy the text",
+      tag: "questions",
+      params: [p("id")],
+      body: SendOwnerAskRequest,
+      ok: { status: 200, schema: "SentOwnerAsk", description: "Sent, or why not" },
+      errors: [400, 403, 404]
+    }
+  },
   "/api/owner-questions/{id}/answer": {
     post: {
       id: "answerOwnerQuestion",
@@ -9576,10 +10335,69 @@ var OPS = {
       errors: [404]
     }
   },
-  "/api/changes/{changeId}/owners": {
-    put: {
-      id: "setChangeOwners",
-      summary: "2.83.0 (ninth UX walk): name the change's owners per role (product owner, architect, business analyst, tech lead) in change.yaml, on the person's click",
+  "/api/changes/{changeId}/owners/suggested": {
+    get: {
+      id: "suggestChangeOwners",
+      summary: "3.6.0 (ADR 0191): who roles.yaml suggests for each role the change doesn't name yet: the team owning its repos, else the organisation's default; a person accepts one with PUT .../owners",
+      tag: "changes",
+      params: [p("changeId")],
+      ok: { status: 200, schema: "OwnerSuggestionList", description: "OK" },
+      errors: [400, 404]
+    }
+  },
+  "/api/changes/{changeId}/work-items": {
+    get: {
+      id: "planWorkItems",
+      summary: "3.6.0 (ADR 0191): the feature, stories and tasks the plan puts in the work tracker, and what sync.yaml remembers of each (atticus ado sync --dry-run)",
+      tag: "changes",
+      params: [p("changeId")],
+      ok: { status: 200, schema: "WorkItemPlan", description: "OK" },
+      errors: [400, 404, 422]
+    },
+    post: {
+      id: "syncWorkItems",
+      summary: "3.6.0 (ADR 0191): put them in the work tracker as the signed-in person: with a manual tracker a step each (the fields to copy, the id to record); with a live one, on the person's `work-items` confirmation. sync.yaml keeps each id, so a later sync updates rather than duplicates. 3.9.0: with `job: true`, 202 JobAccepted at once; the job's result `answer` is the result, or `problem` when refused",
+      tag: "changes",
+      params: [p("changeId")],
+      body: WorkItemSyncRequest,
+      ok: { status: 200, schema: "WorkItemSyncResult", description: "Synced" },
+      alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job: true`)" },
+      errors: [400, 403, 404, 422]
+    }
+  },
+  "/api/changes/{changeId}/stories/shape": {
+    get: {
+      id: "getStoryShape",
+      summary: "3.6.0 (ADR 0191): the business analyst's renames, splits, merges and added stories, each task's story as the last draft mapped it, and what is uncovered",
+      tag: "changes",
+      params: [p("changeId")],
+      ok: { status: 200, schema: "StoryShapeView", description: "OK" },
+      errors: [400, 404]
+    },
+    post: {
+      id: "shapeStories",
+      summary: "3.6.0 (ADR 0191): rename, split, merge or add a story in plain words, as the signed-in person; a rename and a merge keep the number, a split's new part and an added story take the next free one. The next draft of the stories maps the tasks to them",
+      tag: "changes",
+      params: [p("changeId")],
+      body: StoryShapeRequest,
+      ok: { status: 201, schema: "StoryShapeView", description: "Recorded" },
+      errors: [400, 404, 422]
+    }
+  },
+  "/api/changes/{changeId}/stories/shape/{entryId}/remove": {
+    post: {
+      id: "removeStoryShape",
+      summary: "3.6.0 (ADR 0191): take back a shaping no draft has read yet; one a draft applied stays, and a later one changes it",
+      tag: "changes",
+      params: [p("changeId"), p("entryId")],
+      ok: { status: 200, schema: "StoryShapeView", description: "Removed" },
+      errors: [400, 404, 422]
+    }
+  },
+  "/api/changes/{changeId}/owners": {
+    put: {
+      id: "setChangeOwners",
+      summary: "2.83.0 (ninth UX walk): name the change's owners per role (product owner, architect, business analyst, tech lead) in change.yaml, on the person's click",
       tag: "changes",
       params: [p("changeId")],
       body: ChangeOwnersRequest,
@@ -9604,7 +10422,7 @@ var OPS = {
   "/api/changes/{changeId}/release-prs": {
     post: {
       id: "raiseReleasePrs",
-      summary: "Raise one release PR per code repo from change/<id> into its default branch, as the signed-in person (ADR 0184)",
+      summary: "Raise one release PR per code repo from change/<id> into its default branch, as the signed-in person (ADR 0184). 3.0.0 (ADR 0186): needs the person's confirmation (`release-prs`, the change), else 403",
       tag: "changes",
       params: [p("changeId")],
       body: ReleasePrsRequest,
@@ -9613,18 +10431,18 @@ var OPS = {
         schema: "LinesView",
         description: "Raised: what each repo's release PR said"
       },
-      errors: [400, 404, 422]
+      errors: [400, 403, 404, 422]
     }
   },
   "/api/changes/{changeId}/sync": {
     post: {
       id: "syncChange",
-      summary: "Refresh the change from its hand-off PR and advance it when merged (ADR 0043)",
+      summary: "Refresh the change from its hand-off PR and advance it when merged (ADR 0043). 3.0.0 (ADR 0186): merges a ready PR only with the person's confirmation (`merge`, the change); without one it only reads, and a confirmation that isn't valid is 403",
       tag: "changes",
       params: [p("changeId")],
       body: SyncRequest,
       ok: { status: 200, schema: "ChangeDetail", description: "OK" },
-      errors: [400, 404, 422]
+      errors: [400, 403, 404, 422]
     }
   },
   "/api/changes/{changeId}/artifacts/{artifact}": {
@@ -9667,9 +10485,10 @@ var OPS = {
   "/api/changes/{changeId}/tasks/{taskId}/pr": {
     post: {
       id: "raiseTaskPr",
-      summary: "2.69.0 (sixth UX walk): on the person's yes, push a drafted task's branch and open its PR into the change branch",
+      summary: "2.69.0 (sixth UX walk): on the person's yes, push a drafted task's branch and open its PR into the change branch. 3.0.0 (ADR 0186): needs the person's confirmation (`task-pr`, `<change>/<task>`), else 403",
       tag: "changes",
       params: [p("changeId"), p("taskId")],
+      body: ConfirmedRequest,
       ok: { status: 201, schema: "Task", description: "The task, its PR raised" },
       errors: [403, 404, 409, 422]
     }
@@ -9687,7 +10506,7 @@ var OPS = {
   "/api/changes/{changeId}/tasks/run-ready": {
     post: {
       id: "runReadyTasks",
-      summary: "2.79.0 (ADR 0181 part 4): Run all ready tasks, one task run each in order as one job, stopping on the first that needs a person; the click is the approval for draft, never the pr level",
+      summary: "2.79.0 (ADR 0181 part 4): Run all ready tasks, one task run each in order as one job, stopping on the first that needs a person; the click is the approval for draft, never the pr level. 3.1.0: in model mode 403 unless runtime.yaml sends the key where the person last confirmed",
       tag: "changes",
       params: [p("changeId")],
       body: RunReadyRequest,
@@ -9703,24 +10522,56 @@ var OPS = {
       params: [p("changeId"), p("taskId")],
       body: TaskDoneRequest,
       ok: { status: 200, schema: "Task", description: "The task as tasks.md now says it" },
-      errors: [400, 403, 404]
+      errors: [400, 403, 404, 409]
+    }
+  },
+  "/api/propose/upstream": {
+    post: {
+      id: "setUpstream",
+      summary: "3.3.0 (app-only audit): set the upstream of the branch checked out to the same branch on a remote, a local setting (nothing is sent), as a local job; refused (the job's result says why) for any other branch",
+      tag: "workspace",
+      body: UpstreamRequest,
+      ok: { status: 202, schema: "JobAccepted", description: "Job started" },
+      errors: [400, 409]
+    }
+  },
+  "/api/changes/{changeId}/handoff/push": {
+    post: {
+      id: "pushHandoff",
+      summary: "3.3.0 (app-only audit): Push again: push the open hand-off's branch, kept here when its push failed, by name and never forced; needs the person's confirmation (`handoff`, the change), else 403; 422 with git's words when the push fails",
+      tag: "changes",
+      params: [p("changeId")],
+      body: ConfirmedRequest,
+      ok: { status: 200, schema: "ChangeDetail", description: "The change, its branch pushed" },
+      errors: [403, 404, 422]
+    }
+  },
+  "/api/changes/{changeId}/tasks/{taskId}/build": {
+    post: {
+      id: "buildTask",
+      summary: "3.3.0 (app-only audit): Build and raise PR on a task drafted but not built (UNVERIFIED) or taken over by a person: build it with its repo's build command as it is now, and with `raise` push its branch and open its PR (needs the person's confirmation, `task-pr`, `<change>/<task>`, else 403)",
+      tag: "changes",
+      params: [p("changeId"), p("taskId")],
+      body: TaskBuildRequest,
+      ok: { status: 200, schema: "Task", description: "The task, built (201 with its PR raised)" },
+      errors: [400, 403, 404, 409, 422]
     }
   },
   "/api/changes/{changeId}/workspace": {
     post: {
       id: "openWorkspace",
-      summary: "Create the change's worktrees and editor workspaces",
+      summary: "Create the change's worktrees and editor workspaces; 3.1.0: 409 while a sync of one of its repos' base clones runs elsewhere",
       tag: "changes",
       params: [p("changeId")],
       body: OpenWorkspaceRequest,
       ok: { status: 200, schema: "ChangeRepos", description: "OK" },
-      errors: [400, 404]
+      errors: [400, 404, 409]
     }
   },
   "/api/changes/{changeId}/handoff": {
     post: {
       id: "handOff",
-      summary: "Open the phase's hand-off PR after its gate passes",
+      summary: "Open the phase's hand-off PR after its gate passes. 3.0.0 (ADR 0186): needs the person's confirmation (`handoff`, the change), else 403",
       tag: "changes",
       params: [p("changeId")],
       body: HandoffRequest,
@@ -9739,12 +10590,12 @@ var OPS = {
     },
     post: {
       id: "startRun",
-      summary: "Prepare an AI run (hand-off by default)",
+      summary: "Prepare an AI run (hand-off by default); 3.1.0: in model mode 403 unless runtime.yaml sends the key where the person last confirmed (ADR 0186 addendum), and 409 while a sync of the task's repo runs elsewhere",
       tag: "ai",
       params: [p("changeId")],
       body: StartRunRequest,
       ok: { status: 201, schema: "RunView", description: "Prepared" },
-      errors: [400, 403, 404, 422]
+      errors: [400, 403, 404, 409, 422]
     }
   },
   "/api/changes/{changeId}/critic": {
@@ -9782,7 +10633,7 @@ var OPS = {
     },
     post: {
       id: "startStep",
-      summary: "Start an AI step on the server with runtime.yaml's model, as a job (ADR 0106); 409 when no model is configured, or (2.68.0) while another AI step runs",
+      summary: "Start an AI step on the server with runtime.yaml's model, as a job (ADR 0106); 409 when no model is configured, or (2.68.0) while another AI step runs; 3.1.0: 403 unless runtime.yaml sends the key where the person last confirmed (ADR 0186 addendum)",
       tag: "ai",
       body: StartStepRequest,
       ok: {
@@ -9790,7 +10641,7 @@ var OPS = {
         schema: { type: "object", required: ["jobId", "model"] },
         description: "Started"
       },
-      errors: [400, 409]
+      errors: [400, 403, 409]
     }
   },
   "/api/runs/handoff": {
@@ -9870,6 +10721,67 @@ var OPS = {
       errors: [409]
     }
   },
+  "/api/facts/apply-all": {
+    post: {
+      id: "applyAllFacts",
+      summary: "3.5.0 (ADR 0188): run atticus verify --all --write as a local job, as Apply after a declaration or an owner set on the canvas",
+      tag: "workspace",
+      ok: {
+        status: 202,
+        schema: "JobAccepted",
+        description: "Started: its job's result is the code and the lines verify printed"
+      },
+      errors: [409]
+    }
+  },
+  "/api/estate/join": {
+    post: {
+      id: "joinEstate",
+      summary: "3.5.0 (ADR 0188): run atticus estate join as a local job: each flow's calls to other repos followed into the flows they reach",
+      tag: "workspace",
+      ok: { status: 202, schema: "JobAccepted", description: "Job started" },
+      errors: [409]
+    }
+  },
+  "/api/knowledge/sources/sync": {
+    post: {
+      id: "syncAllKnowledgeSources",
+      summary: "3.5.0 (ADR 0188): run atticus sources sync as a local job: every wiki in sources.yaml read into a dated snapshot",
+      tag: "knowledge",
+      ok: { status: 202, schema: "JobAccepted", description: "Job started" },
+      errors: [409]
+    }
+  },
+  "/api/workspace/prune": {
+    post: {
+      id: "pruneWorktrees",
+      summary: "3.5.0 (ADR 0188): run atticus workspace prune as a local job, for one change or every change with worktrees; a worktree with uncommitted work is kept",
+      tag: "workspace",
+      body: PruneRequest,
+      ok: { status: 202, schema: "JobAccepted", description: "Job started" },
+      errors: [400, 409]
+    }
+  },
+  "/api/changes/{changeId}/tasks/{taskId}/context": {
+    get: {
+      id: "getTaskContext",
+      summary: "3.5.0 (ADR 0188): a task's context as atticus task context --markdown prints it, for the person to copy into their assistant",
+      tag: "changes",
+      params: [p("changeId"), p("taskId")],
+      ok: { status: 200, schema: "TaskContextView", description: "OK" },
+      errors: [400]
+    }
+  },
+  "/api/history/recording": {
+    put: {
+      id: "setPromptHistoryRecording",
+      summary: "3.5.0 (ADR 0188): atticus history on|off, this machine's recording (.atticus/me.yaml); the org pack's history.record: false still holds",
+      tag: "ai",
+      body: HistoryRecordingRequest,
+      ok: { status: 200, schema: "HistoryRecordingView", description: "OK" },
+      errors: [400]
+    }
+  },
   "/api/upgrade": {
     get: {
       id: "getUpgrade",
@@ -9885,6 +10797,131 @@ var OPS = {
       errors: [409]
     }
   },
+  // ADR 0190: settings and setup in the app, "Edit, then Propose".
+  "/api/setup/metarepo": {
+    get: {
+      id: "getSetupMetarepo",
+      summary: "3.5.0 (ADR 0190): whether the folder the app runs in is a metarepo, and what Create the metarepo here would use (a name and platform from the folder's name, the metarepo's id on the Git host from its origin)",
+      tag: "run",
+      ok: { status: 200, schema: "SetupMetarepoView", description: "OK" }
+    },
+    post: {
+      id: "createMetarepo",
+      summary: "Create the metarepo in this folder with atticus init's own code (name, platform, owner; the Git host manual, with the metarepo's id when given or read from origin), brought up to date as init does. Local files only: nothing is pushed. 409 when it is a metarepo already",
+      tag: "run",
+      body: CreateMetarepoRequest,
+      ok: { status: 201, schema: "LinesView", description: "Created" },
+      errors: [400, 409, 422]
+    }
+  },
+  "/api/setup/open": {
+    post: {
+      id: "openFolder",
+      summary: "Open another folder: start the app for that folder (a full path on this machine) on a free port, for the same person, and give its address; a folder that isn't a metarepo offers Create there",
+      tag: "run",
+      body: OpenFolderRequest,
+      ok: { status: 200, schema: "OpenFolderView", description: "OK" },
+      errors: [400, 404]
+    }
+  },
+  "/api/setup/repos/plan": {
+    post: {
+      id: "planRepos",
+      summary: "The repos pasted clone URLs (one a line, up to 500) or a folder of clones (repos discover's own code, a dry run) would add: each normalised URL and the id repo add gives it, a clone URL a manifest lists already left out, a taken id given -2, and a folder's type from its files. A folder with several platforms and none given reads nothing and answers the platforms to choose from (`platforms`, no `platform`). Writes nothing",
+      tag: "run",
+      body: ReposPlanRequest,
+      ok: { status: 200, schema: "ReposPlanView", description: "OK" },
+      errors: [400, 404, 409, 422]
+    }
+  },
+  "/api/setup/repos": {
+    post: {
+      id: "addRepos",
+      summary: "Add the repos the person ticked to the platform's repos.manifest.yaml (core's addManifestRepos: comments, order and line endings kept, the manifest checked first); a description is the person's own (verified). With preview: the lines it would change, nothing written. Propose for review then opens the PR",
+      tag: "run",
+      body: AddReposRequest,
+      ok: { status: 200, schema: "FileEditView", description: "OK" },
+      errors: [400, 404, 409, 422]
+    }
+  },
+  "/api/repos/{repoId}/type/detect": {
+    post: {
+      id: "detectRepoType",
+      summary: "Detect a cloned repo's type: the org pack's repo types (atticus repo-type detect) when it has any, else the type repo add reads from the files. Writes nothing; 409 when the repo isn't cloned here",
+      tag: "run",
+      params: [p("repoId")],
+      ok: { status: 200, schema: "RepoTypeDetectView", description: "OK" },
+      errors: [404, 409, 422]
+    }
+  },
+  "/api/repos/{repoId}/type": {
+    put: {
+      id: "setRepoType",
+      summary: "Set a repo's type in the manifest that lists it (comments and order kept); with preview, the line it would change",
+      tag: "run",
+      params: [p("repoId")],
+      body: RepoTypeRequest,
+      ok: { status: 200, schema: "FileEditView", description: "OK" },
+      errors: [400, 404, 422]
+    }
+  },
+  "/api/setup/adapters": {
+    get: {
+      id: "getAdapters",
+      summary: "The outside systems runtime.yaml names (Git host, work tracker, service desk, notifications, wiki, design tool): the types its schema takes for each, the settings Atticus reads, what is set now, and runtime.yaml's sha256 to send back with a write. No secret is ever in them",
+      tag: "run",
+      ok: { status: 200, schema: "AdaptersView", description: "OK" }
+    }
+  },
+  "/api/setup/adapters/{kind}": {
+    put: {
+      id: "setAdapter",
+      summary: "Set (or with null, take out) one outside system in runtime.yaml, checked with the Runtime schema first (a type it doesn't take, a setting named like a secret or a value that looks like a token is refused, 422); edited in place, so comments, value types and line endings are kept. With `baseSha256` (GET's `sha256`), a runtime.yaml changed since is 409. With preview, the lines it would change. A token is kept in the credential store from the terminal (atticus secret set), never through this API",
+      tag: "run",
+      params: [p("kind")],
+      body: AdapterRequest,
+      ok: { status: 200, schema: "FileEditView", description: "OK" },
+      errors: [400, 404, 409, 422]
+    }
+  },
+  "/api/setup/file": {
+    get: {
+      id: "getOrgPackFile",
+      summary: "One org-pack file for the raw editor (a path inside org-pack/ ending .yaml, .md, .txt or .json): its text, its sha256 and whether it is checked with a schema",
+      tag: "run",
+      params: [q("path")],
+      ok: { status: 200, schema: "OrgPackFileView", description: "OK" },
+      errors: [404, 422]
+    },
+    put: {
+      id: "putOrgPackFile",
+      summary: "The raw editor's write, the fallback for a setting with no form: the file's whole text, checked with its schema (YAML that doesn't parse, or doesn't read, is 422), onto the file as opened (another edit meanwhile is 409). With preview, the lines it would change. A runtime.yaml edit that moves where the model's key goes needs the person's confirmation (`ai-model`, `model`), else 403; a value that looks like a key is refused",
+      tag: "run",
+      body: OrgPackFileRequest,
+      ok: { status: 200, schema: "FileEditView", description: "OK" },
+      errors: [400, 403, 409, 422]
+    }
+  },
+  "/api/setup/patterns": {
+    post: {
+      id: "addPattern",
+      summary: "A new integration pattern from the app's form, as its own org-pack/patterns/<code>.yaml, checked with the pattern schema; a code that is there already is 409 (edit it in the raw editor). With preview, the lines it would write",
+      tag: "run",
+      body: PatternRequest,
+      ok: { status: 200, schema: "FileEditView", description: "OK" },
+      errors: [400, 409, 422]
+    }
+  },
+  "/api/setup/sources": {
+    post: {
+      id: "addSource",
+      summary: "A wiki added to sources.yaml with atticus sources add's own code (its checks, its id, the path written relative to the org pack); comments and line endings kept. A location with a user name or password in it is refused (422: Git's credential helper or an environment variable gives them), and so is a sources.yaml changed meanwhile (409). With preview, the entry it would add",
+      tag: "run",
+      body: SourceRequest,
+      ok: { status: 200, schema: "FileEditView", description: "OK" },
+      errors: [400, 409, 422]
+    }
+  },
   "/api/decisions": {
     get: {
       id: "getDecisions",
@@ -10070,6 +11107,24 @@ var OPS = {
       errors: [404]
     }
   },
+  "/api/activity": {
+    get: {
+      id: "listActivity",
+      summary: "Everything Atticus is doing or did lately on this metarepo, newest first: the app's jobs, a Copilot run, the commands run in a terminal, an editor or a Copilot session, and the hand-off runs that wait for an assistant (ADR 0187)",
+      tag: "ai",
+      ok: { status: 200, schema: "ActivityList", description: "OK" }
+    }
+  },
+  "/api/activity/{id}/lines": {
+    get: {
+      id: "getActivityLines",
+      summary: "One activity's printed lines from a line on (from), or its last ones; a Copilot run's are its tabs (ADR 0187)",
+      tag: "ai",
+      params: [p("id"), q("from", str3, "The number of the first line wanted")],
+      ok: { status: 200, schema: "ActivityLines", description: "OK" },
+      errors: [400, 404]
+    }
+  },
   "/api/copilot-runs/{runId}/stop": {
     post: {
       id: "stopCopilotRun",
@@ -10118,10 +11173,13 @@ var OPS = {
   "/api/runs/{runId}/done": {
     post: {
       id: "markRunDone",
-      summary: "Mark done: validate the hand-off output now. 2.67.0 (fourth UX walk): a step the app prepared then resumes, writing what the answer said; `lines` says what happened and `next` names the step's next run when it offers another prompt",
+      summary: "Mark done: validate the hand-off output now. 2.67.0 (fourth UX walk): a step the app prepared then resumes, writing what the answer said; `lines` says what happened and `next` names the step's next run when it offers another prompt. 3.5.0 (ADR 0188): a read of a repo's last batch is put on the map (verify --write), named in `applied`. 3.9.0: with `job: true`, 202 JobAccepted at once; the job's result `answer` is this view, or `problem` when refused",
       tag: "ai",
       params: [p("runId")],
+      body: RunDoneRequest,
+      bodyOptional: true,
       ok: { status: 200, schema: "RunDoneView", description: "OK" },
+      alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job: true`)" },
       errors: [404, 409, 422]
     }
   },
@@ -10155,9 +11213,10 @@ var OPS = {
         q("gate"),
         q("state"),
         q("lens", { type: "string", enum: Lens.options }),
-        q("severity", { type: "string", enum: Severity.options })
+        q("severity", { type: "string", enum: Severity.options }),
+        q("asks", { type: "string", enum: ["business", "design", "delivery"] }, "3.6.0 (ADR 0191): only findings that ask at this level")
       ],
-      ok: { status: 200, schema: arrayOf("Finding"), description: "OK" }
+      ok: { status: 200, schema: arrayOf("FindingView"), description: "OK" }
     }
   },
   "/api/findings/{changeId}/{findingId}": {
@@ -10223,12 +11282,12 @@ var OPS = {
     },
     post: {
       id: "runStep",
-      summary: "Run a step with a team's own tool; the shown inputs' sha-256 is the approval",
+      summary: "Run a step with a team's own tool on the shown inputs (their sha-256). 3.0.0 (ADR 0186): needs the person's confirmation (`step-run`, the step), else 403",
       tag: "release",
       params: [p("stepId")],
       body: StepRunRequest,
       ok: { status: 200, schema: { type: "object" }, description: "OK" },
-      errors: [400, 404, 422]
+      errors: [400, 403, 404, 422]
     }
   },
   "/api/release": {
@@ -10391,11 +11450,11 @@ var OPS = {
     },
     put: {
       id: "putAiSettings",
-      summary: "Write the AI settings to runtime.yaml: checked against the Runtime schema, keeping what it doesn't change; refuses anything that looks like a key. 2.84.0: takes decide (ADR 0181: links, questions, minPrecision), lifting a version 3 file to 4",
+      summary: "Write the AI settings to runtime.yaml: checked against the Runtime schema, keeping what it doesn't change; refuses anything that looks like a key. 2.84.0: takes decide (ADR 0181: links, questions, minPrecision), lifting a version 3 file to 4. 3.0.0 (ADR 0186): keyEnv is a variable starting ATTICUS_, one of the model providers' own key names (the list is in the model-providers package) or a name kept in this machine's credential store (422 otherwise); a change of the provider, keyEnv or an address needs the person's confirmation (`ai-model`, `model`) as `confirmation`, else 403",
       tag: "run",
       body: z30.record(z30.string(), z30.unknown()),
       ok: { status: 200, schema: { type: "object" }, description: "OK" },
-      errors: [409, 422]
+      errors: [403, 409, 422]
     }
   },
   "/api/component-types": {
@@ -10419,10 +11478,11 @@ var OPS = {
   "/api/settings/ai/test": {
     post: {
       id: "testAiProvider",
-      summary: "Ask the configured model provider one short question with nothing of the estate in it, and say whether it answered",
+      summary: "Ask the configured model provider one short question with nothing of the estate in it, and say whether it answered. 3.0.0 (ADR 0186): when runtime.yaml's model settings differ from the committed ones (HEAD), it needs the person's confirmation (`ai-test`, `model`), else 403. 3.1.0: also whenever they send the key to an address the person hasn't confirmed, committed or not; a confirmed Test makes it the confirmed address",
       tag: "run",
+      body: ConfirmedRequest,
       ok: { status: 200, schema: { type: "object" }, description: "OK" },
-      errors: [409]
+      errors: [403, 409]
     }
   },
   "/api/settings/executors/check": {
@@ -10554,6 +11614,17 @@ var OPS = {
       errors: [404, 422]
     }
   },
+  "/api/questions/{id}/route": {
+    post: {
+      id: "routeQuestion",
+      summary: "3.6.0 (ADR 0191): move a question to another role (product, architecture, analysis, delivery), as the signed-in person; the question keeps its answer, and `routed` says from which role, by whom and when",
+      tag: "questions",
+      params: [p("id")],
+      body: RouteQuestionRequest,
+      ok: { status: 200, schema: { type: "object" }, description: "The question, routed" },
+      errors: [400, 404, 422]
+    }
+  },
   "/api/questions/{id}/answer": {
     post: {
       id: "answerQuestion",
@@ -10648,6 +11719,16 @@ var OPS = {
       errors: [400, 404, 422]
     }
   },
+  "/api/knowledge/passage": {
+    get: {
+      id: "knowledgePassage",
+      summary: "3.6.0 (ADR 0191): one section of a wiki snapshot page or an inputs/ file, by its id (<source>/<page>#<heading>), to open it in place",
+      tag: "knowledge",
+      params: [q("id", str3, "The section's id, as a change's knowledge lists it")],
+      ok: { status: 200, schema: "KnowledgePassageView", description: "OK" },
+      errors: [400, 404]
+    }
+  },
   "/api/knowledge/search": {
     get: {
       id: "searchWikis",
@@ -10787,6 +11868,25 @@ var OPS = {
       errors: [400, 404, 409, 422]
     }
   },
+  "/api/changes/{changeId}/stages/{stage}/thread": {
+    get: {
+      id: "getStageThread",
+      summary: "3.5.0 (ADR 0189): a stage of the change as one conversation: the prompts, the assistant's answers and their checks, the critic's findings, the questions, the replies and corrections, and the questions that couldn't be kept, in order",
+      tag: "changes",
+      params: [p("changeId"), p("stage", { schema: { type: "string", enum: [...THREAD_STAGES] } })],
+      ok: { status: 200, schema: "StageThreadView", description: "OK" },
+      errors: [400, 404]
+    },
+    post: {
+      id: "postToStageThread",
+      summary: "3.5.0 (ADR 0189): a person's reply to the stage's assistant (read by its next round as their answer), a comment on a finding, or keeping a dropped question anyway",
+      tag: "changes",
+      params: [p("changeId"), p("stage", { schema: { type: "string", enum: [...THREAD_STAGES] } })],
+      body: StageThreadPost,
+      ok: { status: 200, schema: "StageThreadPostResult", description: "Written" },
+      errors: [400, 404, 409, 422]
+    }
+  },
   "/api/changes/{changeId}/knowledge": {
     get: {
       id: "getChangeKnowledge",
@@ -10891,9 +11991,266 @@ import { isMap as isMap8, parseDocument as parseDocument8 } from "yaml";
 // packages/core/dist/runtime-migrate.js
 import { isMap as isMap9, parseDocument as parseDocument9 } from "yaml";
 
+// packages/core/dist/glob.js
+var notSlash = (c) => c !== "/";
+var anyChar = (c) => !/[\n\r\u2028\u2029]/.test(c);
+var Builder = class {
+  states = [];
+  add(s) {
+    this.states.push(s);
+    return this.states.length - 1;
+  }
+  /** `c*` looping on a test, then on to next. */
+  loop(test, next) {
+    const split = this.add({ kind: "split", outs: [] });
+    const ch = this.add({ kind: "char", test, out: split });
+    this.states[split].outs.push(ch, next);
+    return split;
+  }
+  /** `(?:.*\/)?` then next: any folders, or none. */
+  folders(next) {
+    const slash = this.add({ kind: "char", test: (c) => c === "/", out: next });
+    return this.add({ kind: "split", outs: [this.loop(anyChar, slash), next] });
+  }
+};
+function tidy(glob) {
+  return glob.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function compile(b, g, next) {
+  const pieces = [];
+  for (let i = 0; i < g.length; i++) {
+    const ch = g[i];
+    if (ch === "*") {
+      if (g[i + 1] === "*") {
+        const slash = g[i + 2] === "/";
+        pieces.push(slash ? (n) => b.folders(n) : (n) => b.loop(anyChar, n));
+        i += slash ? 2 : 1;
+      } else
+        pieces.push((n) => b.loop(notSlash, n));
+    } else if (ch === "?")
+      pieces.push((n) => b.add({ kind: "char", test: notSlash, out: n }));
+    else if (ch === "[") {
+      const end = g.indexOf("]", i + 2);
+      if (end < 0)
+        pieces.push(lit("["));
+      else {
+        const body = g.slice(i + 1, end).replace(/^!/, "^").replace(/\\/g, "\\\\");
+        const re = new RegExp(`^[${body}]$`);
+        pieces.push((n) => b.add({ kind: "char", test: (c) => re.test(c), out: n }));
+        i = end;
+      }
+    } else if (ch === "{") {
+      const end = g.indexOf("}", i);
+      if (end < 0)
+        pieces.push(lit("{"));
+      else {
+        const parts = g.slice(i + 1, end).split(",").map((p2) => {
+          let t = tidy(p2);
+          if (t.startsWith("/"))
+            t = t.slice(1);
+          return t;
+        });
+        const probe = new Builder();
+        for (const p2 of parts)
+          compile(probe, p2, probe.add({ kind: "match" }));
+        pieces.push((n) => b.add({ kind: "split", outs: parts.map((p2) => compile(b, p2, n)) }));
+        i = end;
+      }
+    } else
+      pieces.push(lit(ch));
+  }
+  let at = next;
+  for (let k = pieces.length - 1; k >= 0; k--)
+    at = pieces[k](at);
+  return at;
+  function lit(c) {
+    return (n) => b.add({ kind: "char", test: (x) => x === c, out: n });
+  }
+}
+function globMatcher(glob, anyDepth = !glob.replace(/\/$/, "").includes("/")) {
+  let g = tidy(glob);
+  if (g.startsWith("/")) {
+    g = g.slice(1);
+    anyDepth = false;
+  }
+  const b = new Builder();
+  const end = b.add({ kind: "match" });
+  let start = compile(b, g, end);
+  if (anyDepth)
+    start = b.folders(start);
+  const states = b.states;
+  const close = (set, s) => {
+    const stack = [s];
+    while (stack.length) {
+      const at = stack.pop();
+      if (set.has(at))
+        continue;
+      set.add(at);
+      const st = states[at];
+      if (st.kind === "split")
+        for (const o of st.outs)
+          stack.push(o);
+    }
+  };
+  return {
+    test(path) {
+      let live = /* @__PURE__ */ new Set();
+      close(live, start);
+      for (let i = 0; i < path.length; i++) {
+        const c = path[i];
+        const next = /* @__PURE__ */ new Set();
+        for (const s of live) {
+          const st = states[s];
+          if (st.kind === "char" && st.test(c))
+            close(next, st.out);
+        }
+        if (!next.size)
+          return false;
+        live = next;
+      }
+      return live.has(end);
+    }
+  };
+}
+
+// packages/core/dist/repo-files.js
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+var LATIN1_HIGH = (
+  // windows-1252's 0x80-0x9F; the five it leaves undefined keep their C1 code point
+  "\u20AC\x81\u201A\u0192\u201E\u2026\u2020\u2021\u02C6\u2030\u0160\u2039\u0152\x8D\u017D\x8F\x90\u2018\u2019\u201C\u201D\u2022\u2013\u2014\u02DC\u2122\u0161\u203A\u0153\x9D\u017E\u0178"
+);
+var utf8 = new TextDecoder("utf-8", { fatal: true });
+function windows1252(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 8192) {
+    const chunk = bytes.subarray(i, i + 8192);
+    const codes = new Array(chunk.length);
+    for (let j = 0; j < chunk.length; j++) {
+      const b = chunk[j];
+      codes[j] = b >= 128 && b <= 159 ? LATIN1_HIGH.charCodeAt(b - 128) : b;
+    }
+    out += String.fromCharCode(...codes);
+  }
+  return out;
+}
+function utf16(bytes, bigEndian) {
+  const n = bytes.length - bytes.length % 2;
+  const b = Buffer.from(bytes.buffer, bytes.byteOffset, n);
+  if (!bigEndian)
+    return b.toString("utf16le");
+  const swapped = Buffer.from(b);
+  swapped.swap16();
+  return swapped.toString("utf16le");
+}
+function decodeText(bytes) {
+  if (bytes.length >= 2 && bytes[0] === 255 && bytes[1] === 254)
+    return utf16(bytes.subarray(2), false);
+  if (bytes.length >= 2 && bytes[0] === 254 && bytes[1] === 255)
+    return utf16(bytes.subarray(2), true);
+  const body = bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191 ? bytes.subarray(3) : bytes;
+  try {
+    return utf8.decode(body);
+  } catch {
+    return windows1252(body);
+  }
+}
+function ignoreRules(text3, base) {
+  const out = [];
+  for (let line of text3.split(/\r?\n/)) {
+    line = line.replace(/(?<!\\)\s+$/, "");
+    if (!line || line.startsWith("#"))
+      continue;
+    let negate = false;
+    if (line.startsWith("!")) {
+      negate = true;
+      line = line.slice(1);
+    } else if (line.startsWith("\\!") || line.startsWith("\\#"))
+      line = line.slice(1);
+    const dirOnly = line.endsWith("/");
+    if (dirOnly)
+      line = line.slice(0, -1);
+    if (!line)
+      continue;
+    const anchored = line.includes("/");
+    try {
+      out.push({ base, re: globMatcher(line.replace(/^\//, ""), !anchored), negate, dirOnly });
+    } catch {
+    }
+  }
+  return out;
+}
+function ignoredBy(rules, path, isDir) {
+  let out = false;
+  for (const r of rules) {
+    if (r.dirOnly && !isDir)
+      continue;
+    if (r.base && !path.startsWith(`${r.base}/`))
+      continue;
+    const rel = r.base ? path.slice(r.base.length + 1) : path;
+    if (r.re.test(rel))
+      out = !r.negate;
+  }
+  return out;
+}
+var byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+function folder(entries, rel, inherited, gitignore) {
+  const rules = gitignore === void 0 ? inherited : [...inherited, ...ignoreRules(gitignore, rel)];
+  const names = entries.map((e) => e.name);
+  const kept = entries.filter((e) => !e.isSymbolicLink() && e.name !== ".git").sort(byName).map((e) => ({ e, path: rel ? `${rel}/${e.name}` : e.name }));
+  return { rules, names, kept };
+}
+var hasGitignore = (entries) => entries.some((e) => e.name === ".gitignore" && e.isFile());
+async function walkRepo(root, visit, o = {}) {
+  const max = o.max ?? Number.POSITIVE_INFINITY;
+  let files = 0;
+  let cut = false;
+  const go = async (rel, above, inherited) => {
+    const dir = rel ? join(root, ...rel.split("/")) : root;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return true;
+    }
+    const text3 = hasGitignore(entries) ? await readFile(join(dir, ".gitignore")).then(decodeText, () => void 0) : void 0;
+    const { rules, names, kept } = folder(entries, rel, inherited, text3);
+    for (const { e, path } of kept) {
+      if (e.isDirectory()) {
+        if (ignoredBy(rules, path, true) || o.skipFolder?.(above, e.name, names))
+          continue;
+        if (!await go(path, [...above, e.name], rules))
+          return false;
+      } else if (e.isFile()) {
+        if (ignoredBy(rules, path, false))
+          continue;
+        if (files >= max) {
+          cut = true;
+          return false;
+        }
+        files++;
+        if (await visit(path) === false)
+          return false;
+      }
+    }
+    return true;
+  };
+  await go("", [], []);
+  return { files, cut };
+}
+
 // packages/core/dist/log.js
 var LOG_MAX_BYTES = 5 * 1024 * 1024;
 
+// packages/core/dist/run-log.js
+var RUN_LOG_MAX_BYTES = 2 * 1024 * 1024;
+var RUN_SILENT_MS = 5 * 60 * 1e3;
+var DAY = 24 * 60 * 60 * 1e3;
+
+// packages/core/dist/printer.js
+import { AsyncLocalStorage } from "node:async_hooks";
+var printer = new AsyncLocalStorage();
+
 // packages/core/dist/zip-read.js
 var ZIP_LIMITS = {
   maxEntries: 1e4,
@@ -10918,7 +12275,8 @@ var BatchLink = z31.strictObject({
 var BatchQuestion = z31.strictObject({
   kind: z31.literal("question"),
   id: QuestionId,
-  before: QuestionAnswer.optional()
+  before: QuestionAnswer.optional(),
+  proposal: z31.string().min(1).max(65536).optional()
 });
 var BatchItem = z31.discriminatedUnion("kind", [BatchLink, BatchQuestion]);
 var DecisionBatch = z31.strictObject({
@@ -10978,19 +12336,38 @@ var QuestionProposal = z32.strictObject({
   at: IsoDateTime
 });
 
+// packages/core/dist/setup-edit.js
+import { isMap as isMap10, isNode, isScalar, isSeq as isSeq5, parseDocument as parseDocument10, stringify as stringify5 } from "yaml";
+var ADAPTER_KINDS = [
+  "gitHost",
+  "workTracker",
+  "serviceDesk",
+  "notify",
+  "wiki",
+  "design"
+];
+function schemaTypes(kind) {
+  const adapters = Runtime.shape.adapters.unwrap();
+  return adapters.shape[kind]?.unwrap().options.find((o) => o.shape)?.shape?.type.options ?? [];
+}
+var ADAPTER_TYPES = Object.fromEntries(ADAPTER_KINDS.map((k) => [
+  k,
+  ["manual", ...schemaTypes(k).filter((t) => t !== "manual" && t !== "mock")]
+]));
+
 // packages/core/dist/specs.js
 import { parse as parse13 } from "yaml";
 var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSION}`;
 
 // packages/core/dist/cancel.js
-import { AsyncLocalStorage } from "node:async_hooks";
-var store = new AsyncLocalStorage();
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+var store = new AsyncLocalStorage2();
 
 // packages/core/dist/decision-batches.js
-import { parse as parse14, stringify as stringify5 } from "yaml";
+import { parse as parse14, stringify as stringify6 } from "yaml";
 
 // packages/core/dist/declared-links.js
-import { isMap as isMap10, isScalar, isSeq as isSeq5, parseDocument as parseDocument10 } from "yaml";
+import { isMap as isMap11, isScalar as isScalar2, isSeq as isSeq6, parseDocument as parseDocument11 } from "yaml";
 
 // packages/core/dist/schema/reading-rules.js
 import { z as z33 } from "zod";
@@ -11354,8 +12731,20 @@ function globToRegExp(glob) {
 }
 
 // packages/sdk/dist/fs-repo.js
-import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
+import { lstat, readFile as readFile2, realpath, stat } from "node:fs/promises";
+import { join as join2, resolve, sep } from "node:path";
+
+// packages/sdk/dist/listing.js
+var LISTING = /* @__PURE__ */ Symbol.for("@maycombhq/sdk.listing");
+function listingOf(repo) {
+  const v = repo[LISTING];
+  return typeof v === "string" ? v : "";
+}
+function setListing(repo, listing) {
+  Object.defineProperty(repo, LISTING, { value: listing, enumerable: false, configurable: true });
+}
+
+// packages/sdk/dist/fs-repo.js
 var DEFAULT_IGNORES = [
   ".git",
   "node_modules",
@@ -11388,24 +12777,12 @@ function fsRepo(name, dir, commit, options = {}) {
   let cache;
   const sizes = /* @__PURE__ */ new Map();
   const skipped = /* @__PURE__ */ new Map();
-  async function walk(abs, out) {
-    const entries = await readdir(abs, { withFileTypes: true });
-    for (const e of entries) {
-      if (e.isSymbolicLink())
-        continue;
-      const full = join(abs, e.name);
-      if (e.isDirectory()) {
-        if (!ignore.has(e.name))
-          await walk(full, out);
-      } else if (e.isFile()) {
-        out.push(relative(root, full).split(sep).join("/"));
-      }
-    }
-  }
   async function allFiles() {
     if (!cache) {
       const out = [];
-      await walk(root, out);
+      await walkRepo(root, async (p2) => void out.push(p2), {
+        skipFolder: (_above, name2) => ignore.has(name2)
+      });
       cache = out.sort();
     }
     return cache;
@@ -11414,7 +12791,7 @@ function fsRepo(name, dir, commit, options = {}) {
     if (path.startsWith("/") || /^[A-Za-z]:/.test(path) || path.includes("\\") || path.split("/").includes("..")) {
       throw new RepoReadError(`path must be repo-relative with forward slashes: ${path}`, path);
     }
-    const abs = join(root, ...path.split("/"));
+    const abs = join2(root, ...path.split("/"));
     const info = await lstat(abs).catch(() => void 0);
     if (info?.isSymbolicLink())
       throw new RepoReadError(`symbolic links are not read: ${path}`, path);
@@ -11429,7 +12806,7 @@ function fsRepo(name, dir, commit, options = {}) {
       throw new RepoReadError(`file is larger than ${maxBytes} bytes: ${path}`, path);
     return abs;
   }
-  return {
+  const handle = {
     name,
     commit,
     async *listFiles(globs) {
@@ -11438,7 +12815,7 @@ function fsRepo(name, dir, commit, options = {}) {
         if (!matchers.some((m) => m.test(p2)))
           continue;
         if (!sizes.has(p2))
-          sizes.set(p2, (await stat(join(root, ...p2.split("/"))).catch(() => void 0))?.size ?? 0);
+          sizes.set(p2, (await stat(join2(root, ...p2.split("/"))).catch(() => void 0))?.size ?? 0);
         const bytes = sizes.get(p2);
         if (bytes > maxBytes) {
           skipped.set(p2, bytes);
@@ -11452,16 +12829,17 @@ function fsRepo(name, dir, commit, options = {}) {
       return [...skipped].sort(([a], [b]) => a < b ? -1 : 1).map(([path, bytes]) => ({ path, bytes }));
     },
     async readText(path) {
-      const text3 = await readFile(await safePath(path), "utf8");
-      return text3.charCodeAt(0) === 65279 ? text3.slice(1) : text3;
+      return decodeText(await readFile2(await safePath(path)));
     }
   };
+  setListing(handle, JSON.stringify({ ignore: [...ignore].sort(), maxFileBytes: maxBytes, gitignore: true }));
+  return handle;
 }
 
 // packages/sdk/dist/cache.js
 import { createHash as createHash3 } from "node:crypto";
-import { mkdir, readdir as readdir2, readFile as readFile2, rename, rm, writeFile } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { mkdir, readdir as readdir2, readFile as readFile3, rename, rm, writeFile } from "node:fs/promises";
+import { join as join3 } from "node:path";
 var sha256 = (s) => createHash3("sha256").update(s).digest("hex");
 function cacheKeyHash(key) {
   return sha256(JSON.stringify([
@@ -11500,7 +12878,7 @@ function fsScanCache(dir) {
     const h = cacheKeyHash(key);
     return {
       h,
-      path: join2(dir, key.repo, key.commit, `${key.extractor}@${key.version}.${h.slice(0, 16)}.json`)
+      path: join3(dir, key.repo, key.commit, `${key.extractor}@${key.version}.${h.slice(0, 16)}.json`)
     };
   };
   return {
@@ -11508,7 +12886,7 @@ function fsScanCache(dir) {
       const { h, path } = fileFor(key);
       let file;
       try {
-        file = JSON.parse(await readFile2(path, "utf8"));
+        file = JSON.parse(await readFile3(path, "utf8"));
       } catch {
         return void 0;
       }
@@ -11534,7 +12912,7 @@ function fsScanCache(dir) {
         checksum: sha256(JSON.stringify(value)),
         value
       };
-      await mkdir(join2(path, ".."), { recursive: true });
+      await mkdir(join3(path, ".."), { recursive: true });
       const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
       await writeFile(tmp, JSON.stringify(file), "utf8");
       await rename(tmp, path);
@@ -11546,13 +12924,13 @@ function fsScanCache(dir) {
       let removed = 0;
       let commits;
       try {
-        commits = await readdir2(join2(dir, repo));
+        commits = await readdir2(join3(dir, repo));
       } catch {
         return 0;
       }
       for (const c of commits) {
         if (!keep.has(c)) {
-          await rm(join2(dir, repo, c), { recursive: true, force: true });
+          await rm(join3(dir, repo, c), { recursive: true, force: true });
           removed++;
         }
       }
@@ -11657,7 +13035,10 @@ async function scanWith(options) {
         options.configFor?.(extractor) ?? "",
         JSON.stringify(options.repoInfo ?? {}),
         // A changed framework model means a different reading of the same code.
-        options.frameworks?.length ? JSON.stringify(options.frameworks) : ""
+        options.frameworks?.length ? JSON.stringify(options.frameworks) : "",
+        // Review round 49: the same commit listed another way (scan-settings exclusions, the
+        // folders left out, the size limit) gives the extractor other files.
+        listingOf(repo)
       ].join("|")
     };
     try {
@@ -11746,8 +13127,8 @@ async function scanWith(options) {
 
 // packages/sdk/dist/sandbox.js
 import { createHash as createHash4 } from "node:crypto";
-import { readFile as readFile3 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 import { Worker } from "node:worker_threads";
 var PLUGIN_EXTRACTOR_PREFIX = "plugin-";
 var MAX_RECORDS = 1e5;
@@ -11759,7 +13140,7 @@ async function readPinnedEntry(dir, manifest) {
     return { ok: false, message: "isn't pinned: run atticus plugin pin once it is reviewed" };
   let source;
   try {
-    source = await readFile3(join3(dir, ...manifest.entry.split("/")), "utf8");
+    source = await readFile4(join4(dir, ...manifest.entry.split("/")), "utf8");
   } catch (e) {
     return { ok: false, message: `can't read ${manifest.entry}: ${e.message}` };
   }