projectstore-claude 0.30.1 → 0.30.3

package/node_modules/projectstore/scripts/configure.mjs

@@ -22,6 +22,7 @@ import {
 import {
   readOverlayAt,
   resolveAgentModel,
+  resolveAgentEffort,
   layoutRoster,
   readVaultConfigStrict,
   nextVaultConfig,
@@ -35,10 +36,18 @@ import { bandKeys, epicIds, planBand, applyBand } from "./band.mjs";
 import { planAgentsChange, applyAgentsChange } from "./agents-change.mjs";
 import { plan as planInstall, apply as applyInstall, planOptions, isInteractive } from "./install-harness.mjs";
 import { analyseLayout } from "./surfaces.mjs";
+import {
+  knownModels,
+  offListNote,
+  effortSpec,
+  effortLevels,
+  offLevelNote,
+  standingLevelNote,
+  LEVEL,
+} from "./models.mjs";
+import { runMenu } from "./configure-menu.mjs";
+import { SMALLEST } from "./menu.mjs";
 
-// The models the rail offers: the in-session `agents configure` presets
-// (commands/agents.md). Any other model is set with --set (contract 2).
-const MODEL_PRESETS = Object.freeze(["opus", "fable", "sonnet"]);
 const CLEAR = "-";
 
 const LANGUAGE_NOTE =
@@ -76,6 +85,7 @@ export function readFacts(project, { env = process.env, root, home = homedir() }
   return {
     project,
     home,
+    env,
     path,
     cfg,
     used,
@@ -108,6 +118,29 @@ export function settingsOf(f) {
     const o = readOverlayAt(f.project, h.id);
     const file = where(f, o.path);
     const base = { group: `agents:${h.id}`, harness: h.id, file, class: "changeable", team: true, writer: "overlay" };
+    // Each model setting is followed by its effort setting, where the harness
+    // passes one at spawn (the effort ADR, decisions 1 and 4). An effort that
+    // nothing configures reads as the harness says: the frontmatter's, or the
+    // model's own default level, named when its catalog entry is known.
+    const es = effortSpec(h);
+    const known = es?.unset?.model_default ? knownModels(h, { env: f.env, home: f.home }) : null;
+    // frontmatter: the agent's own; model_default: the passed model's own
+    // default, named; harness: the harness's own precedence (no model passed,
+    // or none whose default is known).
+    const unsetEffort = (model) => {
+      if (!es?.unset?.model_default) return { source: "frontmatter" };
+      const d = model ? effortLevels(h, model, known)?.default : null;
+      return d ? { source: "model_default", model_default: d } : { source: "harness" };
+    };
+    const effortRow = (key, effort, effortSource, model) =>
+      es &&
+      out.push({
+        ...base,
+        key,
+        value: effort || null,
+        ...(o.unparseable ? { source: "unparseable" } : effort ? { source: effortSource } : unsetEffort(model)),
+        rail: "effort",
+      });
     out.push({
       ...base,
       key: "agents.default",
@@ -115,7 +148,10 @@ export function settingsOf(f) {
       source: o.unparseable ? "unparseable" : o.agents.default ? "overlay" : "frontmatter",
       rail: "model",
     });
-    const names = [...new Set([...(f.roster || []), ...Object.keys(o.agents.per_agent)])];
+    effortRow("agents.default.effort", o.efforts.default, "overlay", o.agents.default);
+    const names = [
+      ...new Set([...(f.roster || []), ...Object.keys(o.agents.per_agent), ...Object.keys(o.efforts.per_agent)]),
+    ];
     for (const n of names) {
       const r = resolveAgentModel(f.project, n, { harness: h.id });
       out.push({
@@ -125,6 +161,8 @@ export function settingsOf(f) {
         source: o.unparseable ? "unparseable" : r.source || "frontmatter",
         rail: "model",
       });
+      const e = resolveAgentEffort(f.project, n, { harness: h.id });
+      effortRow(`agents.${n}.effort`, e.effort, e.source, r.model);
     }
   }
   if (f.slot)
@@ -239,11 +277,13 @@ function setForm(s, f) {
       ? "on|off"
       : s.key === "tags"
         ? "<a,b>"
-        : s.key.startsWith("agents.")
-          ? "<model>"
-          : s.key === "band.epic"
-            ? "<epic>"
-            : `<${s.key}>`;
+        : s.rail === "effort"
+          ? "<level>"
+          : s.key.startsWith("agents.")
+            ? "<model>"
+            : s.key === "band.epic"
+              ? "<epic>"
+              : `<${s.key}>`;
   const h = s.harness && f.used.length > 1 ? ` --harness ${s.harness}` : "";
   return `--set ${s.key}=${value}${h}`;
 }
@@ -266,8 +306,10 @@ export function resolveSets(f, sets, { harness = null, nearest = null } = {}) {
     const value = String(raw)
       .slice(at + 1)
       .trim();
-    const m = /^agents\.([a-z][a-z0-9-]*)(?:\.model)?$/.exec(key);
-    if (m) key = `agents.${m[1]}`;
+    // agents.<name> and agents.<name>.model are one key; agents.<name>.effort
+    // is a key of its own (the effort ADR, decision 4).
+    const m = /^agents\.([a-z][a-z0-9-]*)(?:\.(model|effort))?$/.exec(key);
+    if (m) key = m[2] === "effort" ? `agents.${m[1]}.effort` : `agents.${m[1]}`;
     if (seen.has(key)) return { usage: `${key} is named twice` };
     seen.add(key);
     if (m) {
@@ -280,6 +322,19 @@ export function resolveSets(f, sets, { harness = null, nearest = null } = {}) {
         else return { usage: `name the overlay: --harness <id> (this project uses ${harnessesNamed})` };
       }
       if (!harnessIds().includes(h)) return { usage: `unknown harness: ${h} — known: ${harnessIds().join(", ")}` };
+      if (m[2] === "effort") {
+        const manifest = loadHarness(h);
+        const es = effortSpec(manifest);
+        if (!es) return { usage: `${manifest?.display_name || h} takes no effort at spawn: ${key} has nothing to set` };
+        // A lowercase token, or - to clear; a level the harness does not list
+        // is written with a note, not refused (decision 5).
+        if (value !== CLEAR && !LEVEL.test(value))
+          return {
+            usage: `${key} takes a level (${es.levels.map((l) => l.id).join(", ")}), or ${CLEAR} to clear it, got ${value || "nothing"}`,
+          };
+        out.push({ key, writer: "overlay", harness: h, name, field: "effort", value: value === CLEAR ? null : value });
+        continue;
+      }
       if (!value) return { usage: `${key} takes a model, or ${CLEAR} to clear it` };
       out.push({ key, writer: "overlay", harness: h, name, value: value === CLEAR ? null : value });
       continue;
@@ -434,20 +489,70 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
   for (const [h, list] of byHarness) {
     const before = readOverlayAt(f.project, h);
     if (before.unparseable) return refuse(`${before.path} is not valid JSON — fix or remove it first`);
-    const def = list.find((c) => c.name === "default");
+    const models = list.filter((c) => c.field !== "effort");
+    const efforts = list.filter((c) => c.field === "effort");
+    const def = models.find((c) => c.name === "default");
+    const defEffort = efforts.find((c) => c.name === "default");
     const change = planAgentsChange({
       before,
       harness: h,
       layout: f.cfg.layout,
       roster: f.roster,
       defaultModel: def ? def.value || "" : undefined,
-      agents: list.filter((c) => c.name !== "default").map((c) => `${c.name}=${c.value || ""}`),
+      agents: models.filter((c) => c.name !== "default").map((c) => `${c.name}=${c.value || ""}`),
+      defaultEffort: defEffort ? defEffort.value || "" : undefined,
+      efforts: efforts.filter((c) => c.name !== "default").map((c) => `${c.name}=${c.value || ""}`),
     });
     if (change.usage) return { usage: change.usage };
     if (change.same) continue;
     const file = where(f, before.path);
-    const display = loadHarness(h).display_name || h;
-    if (before.agents.default !== change.next.default)
+    const manifest = loadHarness(h);
+    const display = manifest.display_name || h;
+    // A model no list of the harness holds is written, with a note (contract
+    // 8 as amended 2026-10-13): the model may be newer than the list.
+    // Only a model the run names gets the note: the clerk's pin does not.
+    const known = knownModels(manifest, { env, home });
+    const named = new Map(models.map((c) => [c.name, c.value]));
+    const offList = (name, model) => (model && named.get(name) === model ? offListNote(manifest, model, known) : null);
+    const notes = (...xs) => xs.filter(Boolean).join("; ") || null;
+    // Effort against the model each agent runs on after the run (the effort
+    // ADR, decision 5): a level the run names is checked on its own row; a
+    // model the run changes is checked against the level its agents keep, on
+    // the model's row; a default level the run names is checked against every
+    // agent that inherits it on a model of its own, on the default's row.
+    const ne = change.nextEfforts;
+    const namedEffort = new Map(efforts.map((c) => [c.name, c.value]));
+    const roster = [
+      ...new Set([...(f.roster || []), ...Object.keys(change.next.per_agent), ...Object.keys(ne.per_agent)]),
+    ];
+    const runModel = (n) => (n === "default" ? change.next.default : change.next.per_agent[n] || change.next.default);
+    const runEffort = (n) => (n === "default" ? ne.default : ne.per_agent[n] || ne.default) || null;
+    const levelNote = (n, level) =>
+      level && namedEffort.get(n) === level ? offLevelNote(manifest, level, runModel(n) || null, known) : null;
+    const inheritors = (level) =>
+      level && namedEffort.get("default") === level
+        ? roster
+            .filter(
+              (n) => !ne.per_agent[n] && change.next.per_agent[n] && change.next.per_agent[n] !== change.next.default,
+            )
+            .map((n) => standingLevelNote(manifest, n, level, runModel(n), known))
+            .filter(Boolean)
+            .join("; ") || null
+        : null;
+    // Agents a model change moves, and the level each keeps, when that level
+    // was not named by this run (a named one is checked on its own row).
+    const moved = (n) => {
+      const who = n === "default" ? ["default", ...roster.filter((r) => !change.next.per_agent[r])] : [n];
+      return (
+        who
+          .filter((a) => !namedEffort.has(a) && !(a !== "default" && !ne.per_agent[a] && namedEffort.has("default")))
+          .map((a) => standingLevelNote(manifest, a, runEffort(a), runModel(a) || null, known))
+          .filter(Boolean)
+          .join("; ") || null
+      );
+    };
+    if (before.agents.default !== change.next.default) {
+      const listNote = notes(offList("default", change.next.default), moved("default"));
       items.push({
         key: "agents.default",
         harness: h,
@@ -456,12 +561,16 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
         before: shown(before.agents.default),
         after: shown(change.next.default),
         team: true,
+        note: listNote,
+        listNote,
       });
+    }
     const names = new Set([...Object.keys(before.agents.per_agent), ...Object.keys(change.next.per_agent)]);
     for (const n of [...names].sort()) {
       const a = before.agents.per_agent[n] || null;
       const b = change.next.per_agent[n] || null;
       if (a === b) continue;
+      const listNote = notes(offList(n, b), moved(n));
       items.push({
         key: `agents.${n}`,
         harness: h,
@@ -470,7 +579,11 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
         before: shown(a),
         after: shown(b),
         team: true,
-        note: change.pinnedClerk && n === "clerk" ? "pinned: the clerk stays cheap under a strong default" : null,
+        note: notes(
+          change.pinnedClerk && n === "clerk" ? "pinned: the clerk stays cheap under a strong default" : null,
+          listNote,
+        ),
+        listNote,
       });
     }
     if (change.clerkPinUnavailable)
@@ -484,7 +597,43 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
         team: true,
         note: `${display} declares no cheap model to pin the clerk to; set agents.clerk to name one`,
       });
-    steps.push({ writer: "overlay", harness: h, next: change.next });
+    const beforeEfforts = before.efforts;
+    if (beforeEfforts.default !== ne.default) {
+      const listNote = notes(levelNote("default", ne.default), inheritors(ne.default));
+      items.push({
+        key: "agents.default.effort",
+        harness: h,
+        display,
+        file,
+        before: shown(beforeEfforts.default),
+        after: shown(ne.default),
+        team: true,
+        note: listNote,
+        listNote,
+      });
+    }
+    const effortNames = new Set([...Object.keys(beforeEfforts.per_agent), ...Object.keys(ne.per_agent)]);
+    for (const n of [...effortNames].sort()) {
+      const a = beforeEfforts.per_agent[n] || null;
+      const b = ne.per_agent[n] || null;
+      if (a === b) continue;
+      const listNote = levelNote(n, b);
+      items.push({
+        key: `agents.${n}.effort`,
+        harness: h,
+        display,
+        file,
+        before: shown(a),
+        after: shown(b),
+        team: true,
+        note: notes(
+          change.pinnedClerkEffort && n === "clerk" ? "pinned: the clerk stays cheap under a strong default" : null,
+          listNote,
+        ),
+        listNote,
+      });
+    }
+    steps.push({ writer: "overlay", harness: h, next: change.next, nextEfforts: ne });
   }
 
   // The status line: install's own plan for the surface, with its flag item
@@ -585,7 +734,7 @@ export function applyChanges(f, steps, { env = process.env, home = homedir(), ro
         writeVaultConfig(f.vault, nextVaultConfig(now.cfg, s.patch, new Date().toISOString()));
         wrote.push(vaultConfigPath(f.vault));
       } else if (s.writer === "overlay") {
-        wrote.push(applyAgentsChange(f.project, s.harness, s.next).path);
+        wrote.push(applyAgentsChange(f.project, s.harness, s.next, s.nextEfforts).path);
       } else if (s.writer === "statusline") {
         const finished = [];
         try {
@@ -623,6 +772,8 @@ const SOURCE_TEXT = Object.freeze({
   per_agent: "per agent",
   default: "default",
   frontmatter: "its frontmatter",
+  model_default: "its model's own default",
+  harness: "the harness decides",
   binding: "binding",
   vault_config: "vault config",
   unparseable: "not valid JSON: fix the file to change it",
@@ -658,9 +809,11 @@ export function renderView(f, settings, { caps: c = term.PLAIN } = {}) {
           note:
             s.class === "other-verb"
               ? "changed by another command, below"
-              : s.class === "changeable" && !s.rail
-                ? `${SOURCE_TEXT[s.source] || s.source}; change it with ${s.set}`
-                : SOURCE_TEXT[s.source] || s.source,
+              : s.source === "model_default" && s.model_default
+                ? `${SOURCE_TEXT.model_default}, ${s.model_default}`
+                : s.class === "changeable" && !s.rail
+                  ? `${SOURCE_TEXT[s.source] || s.source}; change it with ${s.set}`
+                  : SOURCE_TEXT[s.source] || s.source,
         })),
       ),
     );
@@ -711,51 +864,6 @@ export function renderPlan(f, items, { caps: c = term.PLAIN } = {}) {
 
 // ─── The run ───────────────────────────────────────────────────────────
 
-const railChoices = (s, f) => {
-  if (s.rail === "bool") return ["on", "off"];
-  if (s.rail === "language") return f.languages;
-  if (s.rail === "policy") return ["optional", "required"];
-  if (s.rail === "epic") return [...f.epics, { value: CLEAR, label: "release the pin" }];
-  if (s.rail === "model") {
-    // The presets are Claude Code's model names: offered only for a harness
-    // whose agents carry a model (agent_translation.carries_model). Any other
-    // harness's model is named with --set, in its own vocabulary.
-    const list = loadHarness(s.harness)?.agent_translation?.carries_model === true ? [...MODEL_PRESETS] : [];
-    if (s.value && !list.includes(s.value)) list.unshift(s.value);
-    return [...list, { value: CLEAR, label: s.key === "agents.default" ? "clear" : "clear (the default decides)" }];
-  }
-  return [];
-};
-
-// The rail's answers as --set strings, so a terminal run and a named one
-// resolve through the same code.
-async function askRail(rail, f, settings) {
-  const answerable = settings.filter((s) => s.class === "changeable" && s.rail && railChoices(s, f).length);
-  const twoHarnesses = f.used.length > 1;
-  const label = (s) =>
-    twoHarnesses && s.harness
-      ? `${loadHarness(s.harness).display_name || s.harness} · ${s.key.replace(/^agents\./, "")}`
-      : s.key;
-  const ticked = await rail.multi(
-    "What do you want to change?",
-    answerable.map((s, k) => ({ value: k, label: label(s), reason: shown(s.value) })),
-    { min: 0, note: "space ticks a row; Enter with none ticked changes nothing" },
-  );
-  if (ticked === term.CANCELLED) return { cancelled: true };
-  const sets = [];
-  for (const k of ticked) {
-    const s = answerable[k];
-    const choices = railChoices(s, f);
-    const current = s.rail === "bool" ? s.value : s.value || undefined;
-    const v = await rail.select(label(s), choices, {
-      default: choices.some((x) => (typeof x === "object" ? x.value : x) === current) ? current : undefined,
-    });
-    if (v === term.CANCELLED) return { cancelled: true };
-    sets.push({ set: `${s.key}=${v}`, harness: s.harness || null });
-  }
-  return { sets };
-}
-
 // ctx: { values, project, env, stdin, stdout, ask, root, home, ownEnv,
 // nearest, proc, escapeMs, drainTicks, now }. Returns { code, ok, result }
 // or { code: 2, usage } or { code: 3, unbound: true }; the bin writes the
@@ -792,49 +900,87 @@ export async function runConfigure(ctx) {
     harness: s.harness || null,
     team: s.team,
     set: s.set,
+    ...(s.model_default ? { model_default: s.model_default } : {}),
   }));
   const interactive =
     !json && (ask ? true : isInteractive({ stdin, stdout, env, json })) && term.railAvailable(stdin, c);
+  // The menu needs a screen of its own size (contract 4 as amended
+  // 2026-10-13): smaller, the run is as without a terminal.
+  const fits =
+    (Number(stdout?.columns) || c.columns || 100) >= SMALLEST.columns && (Number(stdout?.rows) || 24) >= SMALLEST.rows;
 
   // Nothing named and no terminal: the view, and nothing written.
-  if (!sets.length && !interactive) {
+  if (!sets.length && (!interactive || !fits)) {
     write(renderView(f, settings, { caps: c }));
     return { code: 0, ok: true, result: { settings: publicSettings, plan: [], wrote: [], removed: [] } };
   }
 
   let resolved;
+  // The menu's review screen confirms; a --set run at a terminal asks once.
+  let confirmed = false,
+    reviewed = null;
   if (sets.length) {
     resolved = resolveSets(f, sets, { harness: named[0] || null, nearest: ctx.nearest });
     if (resolved.usage) return { code: 2, usage: resolved.usage };
     write(`${term.badge(c, "projectstore configure")}\n  ${tildeOf(f.project, f.home)}\n`);
   } else {
-    write(renderView(f, settings, { caps: c }));
-    let rail = null,
-      a = null;
-    try {
-      rail = term.openRail({
-        stdin,
-        stdout,
-        caps: c,
-        proc: ctx.proc || process,
-        head: "projectstore configure",
-        ...(ctx.escapeMs ? { escapeMs: ctx.escapeMs } : {}),
-      });
-      a = await askRail(rail, f, settings);
-    } finally {
-      if (rail) rail.close(a?.cancelled ? `Cancelled ${term.icon(c, "dash")} nothing was written` : "");
+    // The settings menu (contract 4 as amended 2026-10-13). Its changes come
+    // back as --set strings and go through the same resolve, plan and apply;
+    // its review screen's second Enter is the confirmation.
+    const resolveAll = (list) => {
+      const changes = [];
+      for (const x of list) {
+        const r = resolveSets(f, [x.set], { harness: x.harness, nearest: ctx.nearest });
+        if (r.usage) return { usage: r.usage };
+        changes.push(...r.changes);
+      }
+      return { changes };
+    };
+    const a = await runMenu({
+      f,
+      settings,
+      stdin,
+      stdout,
+      caps: c,
+      proc: ctx.proc || process,
+      escapeMs: ctx.escapeMs,
+      env,
+      home,
+      now,
+      path: tildeOf(f.project, f.home),
+      dryRun,
+      fetch: ctx.fetch,
+      spawn: ctx.spawn,
+      timers: ctx.timers,
+      review: (list) => {
+        const r = resolveAll(list);
+        if (r.usage) return { ok: false, message: r.usage };
+        const p = planChanges(f, r.changes, { env, home, root, ownEnv: ctx.ownEnv || (() => env) });
+        if (p.usage) return { ok: false, message: p.usage };
+        if (p.refusal !== undefined) return { ok: false, message: p.refusal };
+        return { ok: true, items: p.items, plan: p };
+      },
+    });
+    const head = `${term.badge(c, "projectstore configure")}\n  ${tildeOf(f.project, f.home)}\n`;
+    if (a.cancelled) {
+      write(`${head}\n  Cancelled ${term.icon(c, "dash")} nothing was written\n`);
+      return { code: 130, ok: false, result: null };
     }
-    if (a.cancelled) return { code: 130, ok: false, result: null };
-    const changes = [];
-    for (const x of a.sets) {
-      const r = resolveSets(f, [x.set], { harness: x.harness, nearest: ctx.nearest });
-      if (r.usage) return { code: 2, usage: r.usage };
-      changes.push(...r.changes);
+    if (a.nothing) {
+      write(`${head}\n  No change ${term.icon(c, "dash")} nothing was written\n`);
+      return { code: 0, ok: true, result: { settings: publicSettings, plan: [], wrote: [], removed: [] } };
     }
-    resolved = { changes };
+    write(head);
+    const r = resolveAll(a.sets);
+    if (r.usage) return { code: 2, usage: r.usage };
+    resolved = r;
+    confirmed = !a.dryRun;
+    // What the review showed is what APPLY runs: the plan is not made again
+    // after its confirmation.
+    reviewed = a.planned || null;
   }
 
-  const planned = planChanges(f, resolved.changes, { env, home, root, ownEnv: ctx.ownEnv || (() => env) });
+  const planned = reviewed || planChanges(f, resolved.changes, { env, home, root, ownEnv: ctx.ownEnv || (() => env) });
   if (planned.usage) return { code: 2, usage: planned.usage };
   const planOut = (items) =>
     items.map((i) => ({
@@ -844,6 +990,8 @@ export async function runConfigure(ctx) {
       before: i.before,
       after: i.after,
       team: i.team,
+      // Contract 3 as amended 2026-10-13: the off-list note only.
+      ...(i.listNote ? { note: i.listNote } : {}),
     }));
   if (planned.refusal !== undefined)
     return {
@@ -862,7 +1010,7 @@ export async function runConfigure(ctx) {
     write("\n  Nothing written: this was a dry run.\n");
     return { code: 0, ok: true, result: { ...result, dry_run: true } };
   }
-  if (interactive) {
+  if (interactive && !confirmed) {
     if (stdin && !ask) await term.drainInput(stdin, { ticks: ctx.drainTicks ?? 2 });
     write("\n");
     const yes = await term.askApply(planned.items.length, { stdin, stdout, ask, caps: c });