omp-conductor 0.3.4 → 0.3.6

package/src/setup.ts

@@ -24,6 +24,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { configPath, resolveCaps, stateDir } from "./config.ts";
+import { graphProjectPath, graphRepos } from "./graph.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_AUTHORITY,
@@ -83,6 +84,17 @@ export interface SetupAnswers {
    * that session to drain, rather than starting a second brain.
    */
   orchestratorMode: OrchestratorMode;
+  /**
+   * Parent directory of the index-only clones workers query, or absent when the
+   * operator declined code-graph discovery — in which case no repo gets a
+   * `graphProject` and every rendered brief is the one this package shipped
+   * before graphs existed.
+   *
+   * One answer for the whole project rather than one per repo: the clones are
+   * derived data with no reason to live apart, and a per-repo prompt would ask
+   * the same question four times to arrive at four siblings.
+   */
+  graphRoot?: string;
 }
 
 /** What `gh auth status` says the active token may do. */
@@ -392,18 +404,27 @@ export async function createMissingLabels(trackerRepo: string, plan: LabelPlan[]
  *
  * Split out of `buildConfig` so the plan summary can show the exact project
  * that would be written — including the derived worktree and mirror paths —
- * without assembling a whole config and indexing back into its array.
+ * without assembling a whole config and indexing back into its array. Exported
+ * for the amend summary's before-and-after, and so a test can pin its round-trip
+ * with {@link answersFromProject} — the pair an amend's carry-through rests on.
  */
-function buildProject(a: SetupAnswers): ProjectConfig {
+export function buildProject(a: SetupAnswers): ProjectConfig {
   const dir = stateDir();
 
   const repos: Record<string, RepoTarget> = {};
+  const graphRoot = a.graphRoot?.trim();
   for (const r of a.targetRepos) {
     repos[r.name] = {
       name: r.name,
       cloneUrl: r.cloneUrl,
       defaultBranch: r.defaultBranch,
       gates: r.gates.map((g) => ({ cmd: g.cmd, cwd: g.cwd })),
+      // One answered root becomes one clone per routed repo. Omitted entirely
+      // when unanswered rather than written empty: the key's absence is what
+      // makes an existing config's briefs render exactly as they did before.
+      ...(graphRoot === undefined || graphRoot.length === 0
+        ? {}
+        : { graphProject: graphProjectPath(graphRoot, r.name) }),
     };
   }
 
@@ -467,6 +488,89 @@ export function buildConfig(a: SetupAnswers, existing?: ConductorConfig): Conduc
   };
 }
 
+/**
+ * The seed a brand-new project starts from: the shipped defaults, and nothing
+ * answered yet.
+ *
+ * Exists so "what does an unanswered field start as" has exactly one spelling.
+ * The wizard pre-fills every prompt from an answers object — this one on a first
+ * run, {@link answersFromProject} on a re-run — rather than reaching for a
+ * default at each prompt, which is how one prompt comes to disagree with the
+ * config key it writes.
+ */
+export function defaultAnswers(projectName: string): SetupAnswers {
+  return {
+    projectName,
+    // Empty rather than a plausible guess: both are required, and a pre-filled
+    // tracker repo is the one default an operator would Enter straight past.
+    trackerRepo: "",
+    queueLabel: SETUP_DEFAULTS.queueLabel,
+    stateLabels: { ...SETUP_DEFAULTS.stateLabels },
+    routingLabelPrefix: SETUP_DEFAULTS.routingLabelPrefix,
+    targetRepos: [],
+    caps: {},
+    fallbackToIssueComment: true,
+    authority: { ...SETUP_DEFAULTS.authority },
+    orchestratorMode: SETUP_DEFAULTS.orchestratorMode,
+    reportScope: DEFAULT_REPORT_SCOPE,
+    writeOrchestratorBrief: false,
+  };
+}
+
+/**
+ * The answers that describe a project already on disk — the inverse of
+ * {@link buildProject}, and what makes amending one area possible.
+ *
+ * Every field is derived here, in one function, rather than field by field at
+ * each prompt: an amend asks one area's questions and carries everything else
+ * through untouched, so anything this forgets is a setting the operator loses by
+ * changing an unrelated one. `buildProject(answersFromProject(p))` is pinned to
+ * `p` by a test for exactly that reason.
+ *
+ * Three fields cannot be a straight copy:
+ *
+ * - `writeOrchestratorBrief` is a decision rather than a value, and it starts
+ *   `false` so an amend that never visits the brief area leaves that file alone.
+ * - `reportScope` reads through {@link DEFAULT_REPORT_SCOPE}, because the key is
+ *   optional on disk. A config written before it existed gains it explicitly on
+ *   the next write, saying what it already meant.
+ * - `graphRoot` is one answer for a whole project while the config stores one
+ *   path per repo, so it comes back from whichever repo already has one. Repos
+ *   that disagree — only a hand-edit can produce that — widen to all of them on
+ *   the next write exactly as a full re-run would, and the plan summary names
+ *   every clone before anything is written.
+ */
+export function answersFromProject(p: ProjectConfig): SetupAnswers {
+  const answers: SetupAnswers = {
+    projectName: p.name,
+    trackerRepo: p.tracker.repo,
+    queueLabel: p.queueLabel,
+    stateLabels: { ...p.stateLabels },
+    routingLabelPrefix: p.routing.labelPrefix,
+    targetRepos: Object.values(p.routing.repos).map((r) => ({
+      name: r.name,
+      cloneUrl: r.cloneUrl,
+      defaultBranch: r.defaultBranch,
+      gates: r.gates.map((g) => ({ cmd: g.cmd, cwd: g.cwd })),
+    })),
+    caps: { ...p.caps },
+    fallbackToIssueComment: p.escalation.fallbackToIssueComment,
+    authority: { ...p.authority },
+    orchestratorMode: p.escalation.orchestrator,
+    reportScope: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
+    writeOrchestratorBrief: false,
+  };
+
+  // Set only when present, never as an explicit `undefined`: an absent key is
+  // what keeps the rewritten config identical to the one that was read.
+  if (p.workerModel !== undefined) answers.workerModel = p.workerModel;
+  if (p.escalation.telegramChatId !== undefined) answers.telegramChatId = p.escalation.telegramChatId;
+  const graphed = graphRepos(p)[0];
+  if (graphed !== undefined) answers.graphRoot = dirname(graphed.graphProject);
+
+  return answers;
+}
+
 /**
  * Where a configured project's brief lives: beside its worktrees, under the state
  * directory, so it is on the same disk the fleet already owns and survives a
@@ -694,6 +798,19 @@ export function summarisePlan(
     }
   }
 
+  // Absent entirely when unanswered: a plan for a project with no graph must
+  // read exactly as it did before graphs were a thing this wizard could offer.
+  const graphed = graphRepos(project);
+  if (graphed.length > 0) {
+    lines.push("", "code graph     workers query these clones instead of grepping:");
+    for (const r of graphed) lines.push(`                 ${r.name}  ${r.graphProject}`);
+    lines.push(
+      "               conductor's own index-only clones — nothing human edits them, and",
+      "               nothing here creates them. Run `omp-conductor graph-setup` after",
+      "               setup: it prints the clone, index and systemd-timer commands.",
+    );
+  }
+
   lines.push("", "caps (effective)");
   for (const [key, value] of Object.entries(effective)) {
     const answered = Object.hasOwn(project.caps, key) ? "  (answered)" : "";
@@ -761,3 +878,199 @@ export function summarisePlan(
 
   return lines.join("\n");
 }
+
+/**
+ * Gates as the wizard both shows and reads them back: `cmd`, or `cmd @ cwd` when
+ * one runs from a subdirectory. One spelling, so the pre-filled prompt line and
+ * the amend menu's current value cannot drift apart.
+ */
+export function formatGates(gates: readonly { cmd: string; cwd: string }[]): string {
+  return gates.map((g) => (g.cwd === "." ? g.cmd : `${g.cmd} @ ${g.cwd}`)).join(", ");
+}
+
+/**
+ * The wizard's questions, grouped as the areas a re-run can amend one of, in the
+ * order the full interview asks them.
+ *
+ * Data rather than a switch so the menu, the exhaustiveness of the dialog table
+ * in ./plugin.ts, and the amend summary all enumerate the same eight areas: an
+ * added area fails to compile until it has a name, a current value and a set of
+ * questions.
+ */
+export const AMEND_AREA_IDS = [
+  "tracker",
+  "gates",
+  "caps",
+  "graph",
+  "authority",
+  "escalation",
+  "reporting",
+  "brief",
+] as const;
+
+export type AmendAreaId = (typeof AMEND_AREA_IDS)[number];
+
+/**
+ * The pure half of amend mode: what each area is called, what choosing it asks,
+ * and what it says right now.
+ *
+ * `describe` is the reason the pick-list is worth anything — an operator picking
+ * blind from eight nouns cannot tell which one holds the setting they came to
+ * change, so every row carries its own current value. It reads only the config,
+ * so the whole menu can be rendered and reviewed without a terminal.
+ */
+export const AMEND_AREAS: {
+  readonly [K in AmendAreaId]: {
+    readonly name: string;
+    readonly asks: string;
+    readonly describe: (p: ProjectConfig) => string;
+  };
+} = {
+  tracker: {
+    name: "tracker & repos",
+    asks: "tracker repo, queue and state labels, routing prefix, then every routed repo with its gates",
+    describe: (p) => {
+      const names = Object.values(p.routing.repos).map((r) => r.name);
+      return (
+        `${p.tracker.repo}, queue "${p.queueLabel}", ` +
+        `"${p.routing.labelPrefix}" → ${names.join(", ") || "no repos"}`
+      );
+    },
+  },
+  gates: {
+    name: "gates",
+    asks: "the pre-push commands for each configured repo, and nothing else",
+    describe: (p) => {
+      const repos = Object.values(p.routing.repos);
+      if (repos.length === 0) return "no repos configured";
+      return repos.map((r) => `${r.name}: ${r.gates.length === 0 ? "none" : formatGates(r.gates)}`).join("; ");
+    },
+  },
+  caps: {
+    // The model rides with the caps because it is the other per-worker knob, and
+    // an area no menu offers is a setting only a full re-interview can reach.
+    name: "caps & worker model",
+    asks: "concurrency, spend, turns, wall clock, attempts per issue — then the worker model",
+    describe: (p) => {
+      const c = resolveCaps(p, DEFAULT_CAPS);
+      const answered = Object.keys(p.caps).length > 0;
+      return (
+        `${c.maxConcurrentWorkers} workers, ${c.workerMaxTurns} turns, ` +
+        `${Math.round(c.workerWallClockMs / 60000)}m, $${c.dailySpendUsd}/day, ` +
+        `${c.maxAttemptsPerIssue} attempts${answered ? "" : " (all defaults)"} — ` +
+        `${p.workerModel === undefined ? "harness default model" : `model ${p.workerModel}`}`
+      );
+    },
+  },
+  graph: {
+    name: "code graph",
+    asks: "whether workers query a code-graph index, and the root its one-clone-per-repo lives under",
+    describe: (p) => {
+      const graphed = graphRepos(p);
+      const first = graphed[0];
+      if (first === undefined) return "not configured — workers grep";
+      return `${dirname(first.graphProject)} — ${graphed.length} clone(s): ${graphed.map((r) => r.name).join(", ")}`;
+    },
+  },
+  authority: {
+    name: "authority",
+    asks: "who lands green PRs, and who cuts releases",
+    describe: (p) => `merge=${p.authority.merge}, release=${p.authority.release}`,
+  },
+  escalation: {
+    name: "escalation & triage",
+    asks: "the tier-2 Telegram chat, whether escalations also comment, and where the orchestrator session lives",
+    describe: (p) =>
+      [
+        p.escalation.telegramChatId === undefined
+          ? "tier 2 by issue comment only"
+          : `tier 2 pages Telegram ${p.escalation.telegramChatId}`,
+        p.escalation.fallbackToIssueComment ? "comments too" : "no comment fallback",
+        `triage ${p.escalation.orchestrator}`,
+      ].join(", "),
+  },
+  reporting: {
+    name: "reporting scope",
+    asks: "how much the orchestrator says unprompted",
+    describe: (p) => {
+      const scope = p.reporting?.scope ?? DEFAULT_REPORT_SCOPE;
+      const choice = REPORT_SCOPE_CHOICES.find((c) => c.scope === scope);
+      return `${scope} — ${choice?.description ?? "unknown scope"}`;
+    },
+  },
+  brief: {
+    name: "orchestrator brief",
+    asks: `whether to render ${ORCHESTRATOR_BRIEF_NAME} — the one area that writes no config key`,
+    describe: (p) => {
+      const path = briefPathForProject(p);
+      return existsSync(path) ? `written at ${path}` : `none at ${path}`;
+    },
+  },
+};
+
+/**
+ * How much of a current value fits on a menu row before it costs more than it
+ * tells. Chosen so a four-repo fleet's tracker row — the longest one worth
+ * keeping whole — survives intact. The full text is never lost either way: the
+ * amend summary prints it unelided, and the area's own prompts pre-fill from it.
+ */
+const AMEND_LABEL_MAX = 96;
+
+/**
+ * The amend pick-list, rendered.
+ *
+ * The label carries the current value because the harness's select resolves to
+ * the label it showed, so the row an operator picked has to be recognisable from
+ * its own text alone — and it is the value, not the noun, that tells them
+ * whether this is the row they came for.
+ */
+export function amendChoices(p: ProjectConfig): { id: AmendAreaId; label: string; description: string }[] {
+  return AMEND_AREA_IDS.map((id) => {
+    const area = AMEND_AREAS[id];
+    const current = area.describe(p);
+    return {
+      id,
+      label: `${area.name} — ${current.length > AMEND_LABEL_MAX ? `${current.slice(0, AMEND_LABEL_MAX - 1).trimEnd()}…` : current}`,
+      description: area.asks,
+    };
+  });
+}
+
+/**
+ * What an amend leads its consent screen with: the area, what it said, what it
+ * would say, and the seven areas nobody was asked about.
+ *
+ * The whole plan still follows this, because the confirm has to name every
+ * mutation it authorises — creating labels, writing the config, replacing a
+ * brief — and a delta alone names none of them. What this adds is the sentence
+ * the operator is actually looking for: one area changed, everything else came
+ * back off disk.
+ */
+export function summariseAmend(area: AmendAreaId, before: ProjectConfig, a: SetupAnswers): string {
+  const it = AMEND_AREAS[area];
+  const was = it.describe(before);
+  // The brief is a decision, not a config key, so its "after" is what the wizard
+  // is about to do rather than what a rebuilt project would say.
+  const now =
+    area === "brief"
+      ? a.writeOrchestratorBrief
+        ? `would ${existsSync(orchestratorBriefPath(a)) ? "OVERWRITE" : "write"} ${orchestratorBriefPath(a)}`
+        : "not written — left exactly as it is"
+      : it.describe(buildProject(a));
+
+  const others = AMEND_AREA_IDS.filter((o) => o !== area).map((o) => AMEND_AREAS[o].name);
+  const lines = [`amending       ${it.name}  —  project ${before.name}`];
+  if (was === now) {
+    lines.push(`  no change      ${was}`, "                 you answered through without changing anything here");
+  } else {
+    lines.push(`  was            ${was}`, `  now            ${now}`);
+  }
+  lines.push(
+    `  carried over   ${others.join(", ")}`,
+    `                 read back from ${configPath()} and rewritten unchanged`,
+    "",
+    "The whole project as it would then be written:",
+    "",
+  );
+  return lines.join("\n");
+}

package/src/types.ts

@@ -46,6 +46,31 @@ export interface RepoTarget {
    * subset lets lint errors outside the source dir reach the runners.
    */
   gates: { cmd: string; cwd: string }[];
+  /**
+   * Absolute path of the **conductor-owned, index-only clone** of this repo
+   * whose code-graph index workers query. Optional: absent means this repo has
+   * no graph, and the worker brief says nothing about one.
+   *
+   * Two things it deliberately is not, and both were paid for:
+   *
+   * - **Not a worker's worktree.** A code-graph index is keyed by the realpath
+   *   of the directory it was built from, with no git-worktree awareness, so a
+   *   run's throwaway `worktrees/<issue>` path is always an empty project. A
+   *   worker that queried its own cwd would find nothing, conclude there is no
+   *   graph, and go back to grepping — which is the entire cost this field
+   *   exists to remove.
+   * - **Not a human's checkout.** Refreshing an index means hard-resetting the
+   *   clone to its default branch. Doing that where somebody works destroys
+   *   their uncommitted edits; making it safe instead (a fast-forward pull)
+   *   means the graph reflects whatever feature branch they left checked out.
+   *   So this names a disposable clone nothing human ever edits, which is what
+   *   makes the reset both safe and deterministic.
+   *
+   * `omp-conductor graph-setup` prints how to create and refresh it. Nothing in
+   * this package reads an index itself: the daemon only passes this path into
+   * the worker brief.
+   */
+  graphProject?: string;
 }
 
 /**

package/src/worktree.ts

@@ -8,8 +8,8 @@
  * for the delta.
  */
 
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import type { RepoTarget } from "./types.ts";
 
@@ -96,6 +96,50 @@ async function gitSucceeds(args: string[], cwd?: string): Promise<boolean> {
   return code === 0;
 }
 
+/** Fences the block below so it can be found, replaced, and never duplicated. */
+const EXCLUDE_BEGIN = "# >>> omp-conductor (managed; edit outside this block)";
+const EXCLUDE_END = "# <<< omp-conductor";
+
+/**
+ * Appended to every mirror's `info/exclude`, and so in force in every worktree
+ * cut from it. Deliberately the same shapes salvage therefore skips, and
+ * for the same reason — a worker's own scaffolding is not the repo's business.
+ *
+ * Two layers because they catch different moments: this one keeps scratch out
+ * of a worker's own `git add -A` and out of its `git status`, which salvage
+ * never observes; the salvage list catches whatever a worker created before
+ * this landed, or wrote past an ignore with `add -f`.
+ */
+const LOCAL_EXCLUDE = [".scratch*/", ".scratch*", ".env.local", "*.local.sh"];
+
+/**
+ * Adds the managed block to an `info/exclude`, preserving everything else.
+ *
+ * `info/exclude` is a *local* ignore file, which means it is exactly where an
+ * operator or another tool puts patterns they could not put in the tracked
+ * `.gitignore` — so overwriting it would silently destroy work that has no
+ * other copy. The block is fenced and replaced in place, so re-running this on
+ * every dispatch neither duplicates our lines nor disturbs theirs.
+ */
+export function mergeExclude(existing: string): string {
+  const begin = existing.indexOf(EXCLUDE_BEGIN);
+  const end = existing.indexOf(EXCLUDE_END);
+  const theirs =
+    begin === -1 || end === -1 || end < begin
+      ? existing
+      : existing.slice(0, begin) + existing.slice(end + EXCLUDE_END.length + 1);
+
+  // Normalised before recomposing, so the result is byte-identical on every
+  // call. Trimming the tail matters twice over: a hand-edited file often has no
+  // trailing newline (the first managed line would glue onto their last
+  // pattern and match nothing), and without it the blank separator below would
+  // accumulate one more newline on each of the thousands of dispatches that
+  // call this.
+  const body = theirs.replace(/\n+$/, "");
+  const head = body === "" ? [] : [body, ""];
+  return [...head, EXCLUDE_BEGIN, ...LOCAL_EXCLUDE, EXCLUDE_END, ""].join("\n");
+}
+
 /**
  * Rewrites the two `clone --mirror` defaults that are actively dangerous for a
  * cache we cut worktrees from. Applied on every `ensureMirror` so a mirror left
@@ -122,6 +166,20 @@ async function configureMirror(mirrorPath: string): Promise<void> {
     ["config", "--replace-all", "remote.origin.fetch", TRACKING_REFSPEC],
     mirrorPath,
   );
+
+  // A mirror's `info/exclude` is the common git dir for every worktree cut from
+  // it, so one write here keeps a worker's own scratch out of `git status` in
+  // all of them — without touching the repo's tracked `.gitignore`, which is
+  // the operator's file and not ours to edit.
+  //
+  // Belt and braces with the salvage excludes rather than a replacement for
+  // them: this stops scratch reaching a *worker's* own `git add`, which salvage
+  // never sees. Merged rather than written, because `info/exclude` is precisely
+  // where an operator keeps patterns that cannot go in the tracked file — and
+  // this runs on every dispatch, so overwriting would destroy them repeatedly.
+  const exclude = join(mirrorPath, "info", "exclude");
+  mkdirSync(dirname(exclude), { recursive: true });
+  writeFileSync(exclude, mergeExclude(existsSync(exclude) ? readFileSync(exclude, "utf8") : ""));
 }
 
 /**
@@ -343,7 +401,28 @@ export async function salvageWip(
     const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], worktree);
 
     // `-A` on purpose: the losses this exists for were mostly *new* files.
+    //
+    // Filtering scratch is git's job, not a pathspec's. The mirror's
+    // `info/exclude` (see {@link mergeExclude}) is the common git dir for this
+    // worktree, and git's own rules then give exactly the semantics needed:
+    // untracked ignored files are skipped, while modifications to *tracked*
+    // files are staged even when the name matches an ignore. That second half
+    // is why an exclude pathspec here was wrong — it matched on filename alone,
+    // so a repo legitimately versioning a `bootstrap.local.sh` would have lost
+    // a worker's edits to it, salvage destroying the work it exists to save.
+    //
+    // A literal `:(exclude)<path>` was also an outright bug: git counts it as
+    // naming the path, so an already-ignored file made `add` exit 1 and every
+    // cap-kill would have reported a salvage *failure*.
     await git(["add", "-A"], worktree);
+
+    // The dirty check above ran before git applied its ignores, so a tree whose
+    // only changes were ignored scratch had work by that test and none by this.
+    // Without this, `commit` exits non-zero on an empty index and a tree
+    // holding nothing worth keeping gets reported as a salvage *failure*.
+    if ((await git(["diff", "--cached", "--name-only"], worktree)) === "") {
+      return { kind: "nothing" };
+    }
     await git(
       [
         ...SALVAGE_COMMIT_CONFIG,