omp-conductor 0.3.25 → 0.4.0

package/src/setup.ts

@@ -32,21 +32,39 @@ import {
   refreshComposedBrief,
   renderBriefTemplate,
 } from "./brief-upgrade.ts";
-import { configPath, resolveCaps, resolveReleasePolicy, stateDir } from "./config.ts";
+import {
+  clonePolicy,
+  configPath,
+  resolveCaps,
+  resolveCredentials,
+  resolvePolicy,
+  resolveReleaseGrants,
+  projectTreeBase,
+  stateDir,
+} from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
-  DEFAULT_RELEASE_POLICY,
+  DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DENIED_RELEASE_GRANTS,
+  RELEASE_SHAPES,
+  type CredentialConfig,
+  type CredentialIsolation,
+  type BaseFreshness,
+  type BehindBaseAction,
   type Caps,
   type ConductorConfig,
+  type DraftPolicy,
   type OrchestratorMode,
   type ProjectConfig,
-  type ReleasePolicy,
+  type ProjectPolicy,
+  type ReleaseRequirement,
   type ReportScope,
   type RepoTarget,
+  type ResolvedGrants,
 } from "./types.ts";
 
 /**
@@ -73,8 +91,25 @@ export interface SetupAnswers {
   fallbackToIssueComment: boolean;
   /** How loud the supervising orchestrator session should be. */
   reportScope: ReportScope;
-  /** Mechanical gate for release/deploy-shaped tool calls. */
-  releasePolicy: ReleasePolicy;
+  /**
+   * Mechanical gate for release/deploy-shaped tool calls, per shape. Always
+   * complete: the wizard asks about every shape, so an answer object can never
+   * leave one to be defaulted by whichever reader gets there first (#122).
+   */
+  releaseGrants: ResolvedGrants;
+  /**
+   * What a merge or a release must satisfy before it happens (#129). Always
+   * complete: the wizard asks about every field, so an answers object can never
+   * leave one to be defaulted by whichever reader gets there first.
+   */
+  policy: ProjectPolicy;
+  /**
+   * Whether model-executed code runs under its own OS principal (#125). The
+   * wizard offers `per-run` only when the host probe says this box can build
+   * the boundary, because an answer the host cannot honour is a fleet that
+   * refuses to dispatch rather than a fleet that is protected.
+   */
+  credentials: CredentialConfig;
   /**
    * Whether to render `ORCHESTRATOR.md` into the project's workspace root. Not
    * part of the config — the brief is the operator's file, and the conductor
@@ -135,8 +170,17 @@ export const SETUP_DEFAULTS = {
   defaultBranch: "main",
   /** Both authorities start with the human; the wizard asks to move each one. */
   authority: DEFAULT_AUTHORITY,
-  /** Mechanical release/deploy gate stays closed until explicitly opened. */
-  releasePolicy: DEFAULT_RELEASE_POLICY,
+  /** Every release/deploy shape stays closed until explicitly granted. */
+  releaseGrants: DENIED_RELEASE_GRANTS,
+  /** The strictest reading of the prose these conditions replaced (#129). */
+  policy: DEFAULT_PROJECT_POLICY,
+  /**
+   * No boundary until an operator asks for one on a host that can build it.
+   * `none` is the honest default rather than the safe-sounding one: writing
+   * `per-run` into a fresh config on a box with no mechanism would produce a
+   * conductor that installs cleanly and then declines every issue (#125).
+   */
+  credentials: { isolation: "none" } as CredentialConfig,
   /** The daemon runs its own triage session unless an operator already runs one. */
   orchestratorMode: "embedded",
 } as const;
@@ -160,6 +204,39 @@ export const REPORT_SCOPE_CHOICES: readonly { scope: ReportScope; label: string;
   },
 ];
 
+/**
+ * What each precondition value means to the operator being asked about it, in
+ * their words rather than the gate's.
+ *
+ * Mapped over the closed unions rather than written as parallel arrays, for the
+ * reason {@link MERGE_DUTY} is: a fifth behind-base action fails to compile here
+ * instead of reaching a wizard with no question for it, an amend row that cannot
+ * describe it, and a plan summary that shows it blank. One vocabulary, three
+ * consumers (#129).
+ */
+export const BASE_FRESHNESS_CHOICES: { readonly [K in BaseFreshness]: string } = {
+  "up-to-date": "the head must be level with its base before it may merge",
+  any: "merge whatever the base has moved to since — CI's verdict may be stale",
+};
+
+export const DRAFT_POLICY_CHOICES: { readonly [K in DraftPolicy]: string } = {
+  block: "never merge a draft — the author has said the work is not finished",
+  allow: "a draft may merge when everything else passes",
+};
+
+export const BEHIND_BASE_CHOICES: { readonly [K in BehindBaseAction]: string } = {
+  "update-branch": "run `gh pr update-branch` and wait for the fresh run",
+  hold: "leave it for whoever refreshes it, and merge nothing",
+  escalate: "page a human rather than guess",
+};
+
+export const RELEASE_REQUIREMENT_CHOICES: { readonly [K in ReleaseRequirement]: string } = {
+  "runs-settled": "every run this release covers actually merged, not merely reached a green PR",
+  "no-open-prs": "no pull request is still open against the branch being released",
+  "queue-drained": "nothing still carries the queue label",
+  "epic-children-closed": "the epic this release closes has no open children",
+};
+
 /**
  * The Releases paragraph the brief opens with, one per authority combination.
  *
@@ -425,7 +502,11 @@ export async function createMissingLabels(trackerRepo: string, plan: LabelPlan[]
  * with {@link answersFromProject} — the pair an amend's carry-through rests on.
  */
 export function buildProject(a: SetupAnswers): ProjectConfig {
-  const dir = stateDir();
+  // Under a per-run boundary the worktrees and mirrors have to sit where a slot
+  // principal can actually traverse to them. Defaulting them under the 0700
+  // state directory would provision a repository and then be refused at
+  // dispatch, which looks like a broken install rather than a layout choice.
+  const dir = projectTreeBase(a.credentials.isolation);
 
   const repos: Record<string, RepoTarget> = {};
   const graphRoot = a.graphRoot?.trim();
@@ -456,7 +537,11 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
   // Drops `undefined` members so an unanswered cap is absent from the JSON
   // rather than present-and-null, which the validator would have to reject.
   for (const [key, value] of Object.entries(a.caps) as [keyof Caps, number | undefined][]) {
-    if (typeof value === "number") caps[key] = value;
+    // `planUsage` is the one cap that is not a number, and the wizard does not
+    // ask for it: naming a provider allowance window means reading
+    // `omp usage --json` on the fleet host first, so it stays a documented
+    // hand-edited key (#110). Skipped here to keep this numeric loop honest.
+    if (key !== "planUsage" && typeof value === "number") caps[key] = value;
   }
 
   return {
@@ -471,7 +556,15 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
       : {}),
     escalation,
     authority: { ...a.authority },
-    releasePolicy: a.releasePolicy,
+    // Written out in full, never as the legacy string: the file then says which
+    // shapes are open without anyone having to know a migration rule (#122).
+    releasePolicy: { ...a.releaseGrants },
+    // Written out in full for the same reason: the file then says what a merge
+    // and a release require without anyone having to know a default (#129).
+    policy: clonePolicy(a.policy),
+    // Written out even when it is the default, so `status` reporting the fleet
+    // unprotected always has a line in the file to point at (#125).
+    credentials: { ...a.credentials },
     reporting: { scope: a.reportScope },
     // Both under the state dir so one `rm -rf ~/.omp/conductor` is a complete
     // uninstall, and neither can land in a repo the daemon then tries to commit.
@@ -528,7 +621,9 @@ export function defaultAnswers(projectName: string): SetupAnswers {
     caps: {},
     fallbackToIssueComment: true,
     authority: { ...SETUP_DEFAULTS.authority },
-    releasePolicy: SETUP_DEFAULTS.releasePolicy,
+    releaseGrants: { ...SETUP_DEFAULTS.releaseGrants },
+    policy: clonePolicy(SETUP_DEFAULTS.policy),
+    credentials: { ...SETUP_DEFAULTS.credentials },
     orchestratorMode: SETUP_DEFAULTS.orchestratorMode,
     reportScope: DEFAULT_REPORT_SCOPE,
     writeOrchestratorBrief: false,
@@ -574,7 +669,9 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
     caps: { ...p.caps },
     fallbackToIssueComment: p.escalation.fallbackToIssueComment,
     authority: { ...p.authority },
-    releasePolicy: resolveReleasePolicy(p),
+    releaseGrants: resolveReleaseGrants(p),
+    policy: resolvePolicy(p),
+    credentials: resolveCredentials(p),
     orchestratorMode: p.escalation.orchestrator,
     reportScope: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
     writeOrchestratorBrief: false,
@@ -614,9 +711,27 @@ function briefVarsForProject(p: ProjectConfig): Record<string, string> {
     RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
     MERGE_DUTY: MERGE_DUTY[p.authority.merge],
     REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
+    POLICY_SOURCE: policySourceLine(p),
   };
 }
 
+/**
+ * Where the merge and release conditions actually live, worded for this
+ * project.
+ *
+ * A pointer, deliberately carrying no value from the policy it points at. A
+ * threshold rendered into the standing prompt *and* stored in the config is a
+ * threshold with two copies, and the copy a session reads is the one nobody
+ * updated — which is the failure #129 exists to end. So the brief describes
+ * the policy and names where to read it; it never restates it.
+ */
+function policySourceLine(p: ProjectConfig): string {
+  return (
+    `They are in \`${configPath()}\` under \`projects[] "${p.name}" policy\`, and they change with ` +
+    `\`/conductor setup\` → "${AMEND_AREAS.policy.name}". Never by hand in this file.`
+  );
+}
+
 /** Package floor template, placeholders and all. */
 export function shippedFloorTemplate(): string {
   return readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8");
@@ -907,15 +1022,41 @@ export function summarisePlan(
   );
 
   const delegated = a.authority.merge === "orchestrator" || a.authority.release === "orchestrator";
+  // The consent screen is the last place an unintended grant can be caught, so
+  // it names the shapes rather than a policy word: "operator-brief" is exactly
+  // what the operator in #122 read as safe while it also permitted a deploy.
+  const granted = RELEASE_SHAPES.filter((shape) => a.releaseGrants[shape] === "orchestrator");
   lines.push(
     "",
     `authority      merge=${a.authority.merge}  release=${a.authority.release}`,
-    `tool gate      releasePolicy=${a.releasePolicy}`,
+    `tool gate      ${
+      granted.length === 0
+        ? "every release/deploy shape blocked for workers and the orchestrator"
+        : `orchestrator may invoke ${granted.join(", ")}`
+    }`,
+    ...(granted.length === 0
+      ? []
+      : [
+          `               blocked: ${RELEASE_SHAPES.filter((shape) => a.releaseGrants[shape] !== "orchestrator").join(", ") || "nothing"}`,
+        ]),
     delegated
       ? "               the brief tells that session so, and it must spell the procedure out before acting"
       : "               humans do both; workers and the conductor stop at a green PR",
   );
 
+  lines.push("", "preconditions  what a merge and a release must satisfy — checked mechanically, never re-read from prose");
+  lines.push(
+    `  merge        ${describeChecks(a.policy.merge.requiredChecks, "the PR")}; base ${a.policy.merge.baseFreshness}; ` +
+      `drafts ${a.policy.merge.drafts}; behind base → ${a.policy.merge.whenBehindBase}`,
+    `  release      ${
+      a.policy.release.requires.length === 0
+        ? "nothing has to have landed first"
+        : `needs ${a.policy.release.requires.join(", ")}`
+    }; ${describeChecks(a.policy.release.requiredChecks, "the branch")}`,
+    `  artefacts    ${a.policy.release.artefacts.join(", ") || "none declared — a release verb has nothing to ship"}`,
+    `  environments ${a.policy.release.environments.join(", ") || "none declared — every deploy target is refused"}`,
+  );
+
   const chosen = REPORT_SCOPE_CHOICES.find((c) => c.scope === a.reportScope);
   const briefPath = orchestratorBriefPath(a);
   lines.push(
@@ -948,6 +1089,16 @@ export function summarisePlan(
  * one runs from a subdirectory. One spelling, so the pre-filled prompt line and
  * the amend menu's current value cannot drift apart.
  */
+/**
+ * A required-check list as both the plan and the amend row say it. An empty list
+ * is *stricter* than a named one, so it is spelled out rather than shown as
+ * "none" — an operator reading "checks: none" would reasonably conclude the gate
+ * was open.
+ */
+function describeChecks(checks: readonly string[], reporter: string): string {
+  return checks.length === 0 ? `every check ${reporter} reports` : `checks ${checks.join(", ")}`;
+}
+
 export function formatGates(gates: readonly { cmd: string; cwd: string }[]): string {
   return gates.map((g) => (g.cwd === "." ? g.cmd : `${g.cmd} @ ${g.cwd}`)).join(", ");
 }
@@ -957,7 +1108,7 @@ export function formatGates(gates: readonly { cmd: string; cwd: string }[]): str
  * 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
+ * in ./plugin.ts, and the amend summary all enumerate the same nine areas: an
  * added area fails to compile until it has a name, a current value and a set of
  * questions.
  */
@@ -967,6 +1118,8 @@ export const AMEND_AREA_IDS = [
   "caps",
   "graph",
   "authority",
+  "policy",
+  "credentials",
   "escalation",
   "reporting",
   "brief",
@@ -1042,9 +1195,45 @@ export const AMEND_AREAS: {
   },
   authority: {
     name: "authority",
-    asks: "who lands green PRs, who cuts releases, and whether release/deploy tools are mechanically open",
-    describe: (p) =>
-      `merge=${p.authority.merge}, release=${p.authority.release}, releasePolicy=${resolveReleasePolicy(p)}`,
+    asks: "who lands green PRs, who cuts releases, then one question per release/deploy shape",
+    describe: (p) => {
+      const grants = resolveReleaseGrants(p);
+      const granted = RELEASE_SHAPES.filter((shape) => grants[shape] === "orchestrator");
+      // Counted rather than listed because this row is elided at 96 characters —
+      // and `deploy` is then named on its own, because it is the one grant in the
+      // set that mutates a running environment and the one #122 cost us. The full
+      // table is in `status` and in the amend summary.
+      return (
+        `merge=${p.authority.merge}, release=${p.authority.release}, tools: ` +
+        `${granted.length === 0 ? "all blocked" : `${granted.length}/${RELEASE_SHAPES.length} granted`}` +
+        `, deploy=${grants.deploy}`
+      );
+    },
+  },
+  policy: {
+    name: "merge & release preconditions",
+    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships",
+    describe: (p) => {
+      const policy = resolvePolicy(p);
+      // Counted rather than listed: this row is elided at 96 characters, and the
+      // full table is in the plan summary the consent screen shows next.
+      return (
+        `merge: ${policy.merge.requiredChecks.length === 0 ? "every check" : `${policy.merge.requiredChecks.length} check(s)`}, ` +
+        `base ${policy.merge.baseFreshness}, drafts ${policy.merge.drafts}, behind → ${policy.merge.whenBehindBase}; ` +
+        `release: ${policy.release.requires.length} must-land, ${policy.release.artefacts.length} artefact(s), ` +
+        `${policy.release.environments.length} env(s)`
+      );
+    },
+  },
+  credentials: {
+    name: "credential isolation",
+    asks: "whether worker and orchestrator sessions run under their own OS principal, or as the daemon's own user",
+    describe: (p) => {
+      const c = resolveCredentials(p);
+      return c.isolation === "per-run"
+        ? `per-run principals${c.readToken === undefined ? "" : ", with a read-scoped token"}`
+        : "none — sessions run as the daemon's user and can reach its credentials";
+    },
   },
   escalation: {
     name: "escalation & triage",
@@ -1107,7 +1296,7 @@ export function amendChoices(p: ProjectConfig): { id: AmendAreaId; label: string
 
 /**
  * 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.
+ * would say, and the eight 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