refactor(hub): name the steps an approval opened from the start gates

Author: TheGreatAxios

apps/hub/src/projects/deploy-tools.test.ts

@@ -219,7 +219,6 @@ function writerTools(preferences: Record<string, string> = {}) {
   const documents: Record<string, unknown>[] = [
     { kind: "problem_brief", artifactId: "brief", title: "Brief", version: 2 },
     { kind: "constraints", artifactId: "c", title: "C", version: 1 },
-    { kind: "material", artifactId: "m", title: "M", version: 1 },
   ].map((item) => ({ ...item, sha256: "a".repeat(64) }));
   const deployed: string[] = [];
   const approvals: unknown[] = [];
@@ -298,22 +297,21 @@ const writer = (kind: string) => ({
     "Write the " + kind + " from the filed documents and the person's answers.",
 });
 
-test("an approval names the step it unblocks once every earlier document is approved", async () => {
+test("an approval reports the steps whose gates it opened, unless one is under way", async () => {
   const { run, documents, inFlight } = writerTools();
-  const unblocked = async (kinds: string[]) => {
+  const canStart = async (kinds: string[]) => {
     const result = await run("request_approval", { kinds });
-    return [JSON.parse(String(result.content)).unblocked, result.detail];
+    return [JSON.parse(String(result.content)).canStart, result.detail];
   };
 
-  expect(await unblocked(["problem_brief"])).toEqual([undefined, undefined]);
+  expect(await canStart(["problem_brief"])).toEqual([[], undefined]);
   inFlight.push({ runId: "w", role: "writer", status: "running" });
-  expect(await unblocked(["constraints"])).toEqual([undefined, undefined]);
+  expect(await canStart(["constraints"])).toEqual([[], undefined]);
   inFlight.pop();
-  expect(await unblocked(["constraints"])).toEqual([
-    "approaches",
-    { unblocked: "approaches" },
+  expect(await canStart(["constraints"])).toEqual([
+    ["approaches"],
+    { canStart: ["approaches"] },
   ]);
-  expect(await unblocked(["material"])).toEqual([undefined, undefined]);
 
   for (const kind of ["approaches", "product_requirements"])
     documents.push({
@@ -323,21 +321,12 @@ test("an approval names the step it unblocks once every earlier document is appr
       version: 1,
       sha256: "a".repeat(64),
     });
-  expect(await unblocked(["approaches", "product_requirements"])).toEqual([
-    "design",
-    { unblocked: "design" },
-  ]);
-  documents.push({
-    kind: "design_option",
-    artifactId: "o",
-    title: "Calm",
-    version: 1,
-    sha256: "a".repeat(64),
-  });
-  expect(await unblocked(["product_requirements"])).toEqual([
-    undefined,
-    undefined,
+  expect(await canStart(["approaches", "product_requirements"])).toEqual([
+    ["design"],
+    { canStart: ["design"] },
   ]);
+  inFlight.push({ runId: "d", role: "designer", status: "running" });
+  expect(await canStart(["product_requirements"])).toEqual([[], undefined]);
 });
 
 test("one ask approves several documents, and a writer starts once every earlier one is approved", async () => {

apps/hub/src/projects/deploy-tools.ts

@@ -158,35 +158,6 @@ const ArtifactList = type({
 });
 type Ref = typeof SourceRef.infer;
 
-// A coordinator on 2026-11-05 often read a bare approval as still pending and started nothing, so
-// an approval of a document names the step it unblocks: the document after the last filed one, once
-// every filed document before it is approved and no writer is at work, or the design while none of
-// it is under way. A writer's run ends with its one task, so one in flight is at work.
-function unblockedStep(
-  documents: readonly { kind: string }[],
-  byKind: ReadonlyMap<string, Ref>,
-  approved: ReadonlyMap<string, number>,
-  inFlight: readonly { role: string }[],
-  designOptions: boolean,
-): string | undefined {
-  const approving = (kind: string) =>
-    documents.some((doc) => doc.kind === kind);
-  if (!DOCUMENT_ORDER.some(approving)) return undefined;
-  const index = DOCUMENT_ORDER.findLastIndex((kind) => byKind.has(kind)) + 1;
-  const next = DOCUMENT_ORDER[index];
-  const atWork = (role: string) => inFlight.some((run) => run.role === role);
-  if (next === undefined || atWork("writer")) return undefined;
-  if (next === "design" && (designOptions || atWork("designer")))
-    return undefined;
-  const earlierApproved = DOCUMENT_ORDER.slice(0, index).every(
-    (kind) =>
-      !byKind.has(kind) ||
-      approving(kind) ||
-      approved.get(kind) === byKind.get(kind)?.version,
-  );
-  return earlierApproved ? next : undefined;
-}
-
 interface DeployEnv extends BaseEnv {
   capabilities: RuntimeCapabilities;
 }
@@ -409,13 +380,9 @@ export function createDeployTools(options?: {
           const materials: ArtifactRef[] = [];
           const approved = new Map<string, number>();
           const openQuestions = new Map<string, number>();
-          let designOptions = false;
           for (const item of list.artifacts) {
             const { kind, artifactId, version, sha256, approvedVersion } = item;
-            if (kind === "design_option") {
-              designOptions = true;
-              continue;
-            }
+            if (kind === "design_option") continue;
             if (kind === MATERIAL_KIND)
               materials.push({ kind, artifactId, version, sha256 });
             byKind.set(kind, { artifactId, version, sha256 });
@@ -429,7 +396,6 @@ export function createDeployTools(options?: {
             materials,
             approved,
             openQuestions,
-            designOptions,
             inFlight: list.inFlight,
             preferences: list.preferences,
           };
@@ -476,6 +442,81 @@ export function createDeployTools(options?: {
             );
           return ref;
         };
+        type Listed = Awaited<ReturnType<typeof listed>>;
+        /*
+         * Each start tool refuses through its gate, and an approval reports the steps whose gates
+         * then pass. The coordinator learns what it may start from the rule that enforces it, so
+         * loosening a gate loosens what it is told.
+         */
+        const writerGate = (
+          { byKind, approved, preferences }: Listed,
+          kind: (typeof DOCUMENT_ORDER)[number],
+        ) => {
+          const earlier = DOCUMENT_ORDER.slice(0, DOCUMENT_ORDER.indexOf(kind));
+          // An imported project may lack an earlier document that its later ones were written without.
+          const writtenWithout = (index: number) =>
+            DOCUMENT_ORDER.slice(index + 1).some((later) => byKind.has(later));
+          for (const [index, before] of earlier.entries()) {
+            const ref = byKind.get(before);
+            if (!ref) {
+              if (writtenWithout(index)) continue;
+              throw new Refusal(
+                before +
+                  "_missing: " +
+                  (before === "design"
+                    ? "have the designer make it with design_app"
+                    : "write and file the " + before) +
+                  " before the " +
+                  kind,
+              );
+            }
+            if (
+              !agentDecidesApprovals(preferences) &&
+              approved.get(before) !== ref.version
+            )
+              throw notApproved(before, ref.version);
+          }
+        };
+        const designGate = ({ byKind }: Listed) => {
+          for (const kind of DESIGNER_INPUTS) required(byKind, kind);
+        };
+        const coderGate = ({ byKind, approved, preferences }: Listed) => {
+          for (const kind of CODER_DOCUMENTS) required(byKind, kind);
+          // The design is approved by choosing it, whoever decides the other documents.
+          for (const kind of DOCUMENT_ORDER) {
+            const { version } = required(byKind, kind);
+            if (
+              (kind === "design" || !agentDecidesApprovals(preferences)) &&
+              approved.get(kind) !== version
+            )
+              throw notApproved(kind, version);
+          }
+        };
+        // A step already made or under way is not offered again, whatever its gate says.
+        const startable = (state: Listed) => {
+          const busy = new Set(state.inFlight.map((run) => run.role));
+          const open = (step: string, role: string, gate: () => void) => {
+            if (state.byKind.has(step) || busy.has(role)) return false;
+            try {
+              gate();
+              return true;
+            } catch (error) {
+              if (error instanceof Refusal) return false;
+              throw error;
+            }
+          };
+          return [
+            ...DOCUMENT_ORDER.filter(
+              (kind) =>
+                kind in WRITER_PACKAGES &&
+                open(kind, "writer", () => writerGate(state, kind)),
+            ),
+            ...(open("design", "designer", () => designGate(state))
+              ? ["design"]
+              : []),
+            ...(open("app", "coder", () => coderGate(state)) ? ["app"] : []),
+          ];
+        };
         // A fresh deployment warms its workspace with the current versions, the ones named here.
         const inputs = (
           kinds: readonly InputKind[],
@@ -538,18 +579,11 @@ export function createDeployTools(options?: {
         try {
           signal.throwIfAborted();
           let result: unknown;
-          let unblocked: string | undefined;
+          let canStart: readonly string[] = [];
           if (call.name === "request_approval") {
             const { kinds } = validArguments(RequestApproval, call.arguments);
-            const {
-              byKind,
-              materials,
-              approved,
-              openQuestions,
-              designOptions,
-              preferences,
-              inFlight,
-            } = await listed();
+            const { byKind, materials, openQuestions, preferences } =
+              await listed();
             const open = [...new Set(kinds)].flatMap((kind) => {
               const count = openQuestions.get(kind);
               return count
@@ -572,45 +606,14 @@ export function createDeployTools(options?: {
               return materials;
             });
             await recordApproval("request_approval", documents);
-            unblocked = unblockedStep(
-              documents,
-              byKind,
-              approved,
-              inFlight,
-              designOptions,
-            );
-            result = { approved: documents, unblocked };
+            canStart = startable(await listed());
+            result = { approved: documents, canStart };
           } else if (call.name === "deploy_writer") {
             const input = validArguments(DeployWriter, call.arguments);
-            const { byKind, approved, preferences } = await listed();
+            const state = await listed();
+            const { byKind, preferences } = state;
             const briefRef = required(byKind, "problem_brief");
-            const earlier = DOCUMENT_ORDER.slice(
-              0,
-              DOCUMENT_ORDER.indexOf(input.kind),
-            );
-            // An imported project may lack an earlier document that its later ones were written without.
-            const writtenWithout = (index: number) =>
-              DOCUMENT_ORDER.slice(index + 1).some((kind) => byKind.has(kind));
-            for (const [index, kind] of earlier.entries()) {
-              const ref = byKind.get(kind);
-              if (!ref) {
-                if (writtenWithout(index)) continue;
-                throw new Refusal(
-                  kind +
-                    "_missing: " +
-                    (kind === "design"
-                      ? "have the designer make it with design_app"
-                      : "write and file the " + kind) +
-                    " before the " +
-                    input.kind,
-                );
-              }
-              if (
-                !agentDecidesApprovals(preferences) &&
-                approved.get(kind) !== ref.version
-              )
-                throw notApproved(kind, ref.version);
-            }
+            writerGate(state, input.kind);
             const target = byKind.get(input.kind);
             const sourceRefs = [...byKind]
               .filter(
@@ -672,26 +675,16 @@ export function createDeployTools(options?: {
               options.projectId + ":coder",
               "coder",
               async () => {
-                const { byKind, approved, inFlight, preferences } =
-                  await listed();
-                for (const kind of CODER_DOCUMENTS) required(byKind, kind);
+                const state = await listed();
+                const { byKind, inFlight, preferences } = state;
                 const live = inFlight.find((run) => run.role === "coder");
                 if (live)
                   throw new Refusal(
                     "coder_already_running: the coder is building in run " +
                       live.runId +
                       "; send it changes with instruct_coder",
                   );
-                // The design is approved by choosing it, whoever decides the other documents.
-                for (const kind of DOCUMENT_ORDER) {
-                  const { version } = required(byKind, kind);
-                  if (
-                    (kind === "design" ||
-                      !agentDecidesApprovals(preferences)) &&
-                    approved.get(kind) !== version
-                  )
-                    throw notApproved(kind, version);
-                }
+                coderGate(state);
                 const design = required(byKind, "design");
                 return deploy(
                   "coder",
@@ -745,8 +738,9 @@ export function createDeployTools(options?: {
                 options.projectId + ":designer:" + concept.label,
                 "designer",
                 async () => {
-                  const { byKind, inFlight, preferences } = await listed();
-                  for (const kind of DESIGNER_INPUTS) required(byKind, kind);
+                  const state = await listed();
+                  const { byKind, inFlight, preferences } = state;
+                  designGate(state);
                   const message =
                     designLookIdeas(input.lookIdeas) +
                     coderTaskMessage(input.instruction);
@@ -884,7 +878,7 @@ export function createDeployTools(options?: {
           return {
             callId: call.id,
             content: JSON.stringify(result),
-            ...(unblocked ? { detail: { unblocked } } : {}),
+            ...(canStart.length ? { detail: { canStart } } : {}),
           };
         } catch (error) {
           return {

apps/hub/src/workflows/director.test.ts

@@ -297,7 +297,7 @@ test("designer director holds replies until the latest edits pass check_design a
   expect(accepted.some((action) => action.type === "reply")).toBe(true);
 });
 
-test("coordinator director reminds once after an approval that unblocked a step, unless the reply asks the person", async () => {
+test("coordinator director reminds once after an approval that opened a step, unless the reply asks the person", async () => {
   const subject = () =>
     compactingDirector("@corbits-builder/coordinator-test").factory(
       { contextWindow: 200_000, compactAt: 0.8, startAfterApproval: true },
@@ -344,7 +344,7 @@ test("coordinator director reminds once after an approval that unblocked a step,
       timestamp: 2,
     },
   ];
-  const unblocked = { detail: { unblocked: "product_requirements" } };
+  const opened = { detail: { canStart: ["product_requirements"] } };
   const read: ConversationTurn[] = [
     {
       role: "assistant",
@@ -380,18 +380,18 @@ test("coordinator director reminds once after an approval that unblocked a step,
     );
   };
 
-  expect(await holds([...approval(unblocked), ...read])).toBe(true);
+  expect(await holds([...approval(opened), ...read])).toBe(true);
   expect(await holds(approval())).toBe(false);
-  expect(await holds(approval({ ...unblocked, isError: true }))).toBe(false);
+  expect(await holds(approval({ ...opened, isError: true }))).toBe(false);
   expect(
     await holds(
-      approval(unblocked),
+      approval(opened),
       "Do you want one design or several? Tell me any apps or colours you like.",
     ),
   ).toBe(false);
 
   const director = subject();
-  const turns = approval(unblocked);
+  const turns = approval(opened);
   expect(await holds(turns, undefined, director)).toBe(true);
   const retried = await director.decide(
     {
@@ -406,7 +406,7 @@ test("coordinator director reminds once after an approval that unblocked a step,
     (action) => action.type === "infer",
   );
   expect(infer?.type === "infer" ? infer.options?.systemPrompt : "").toContain(
-    "unblocked product_requirements",
+    "these can start now: product_requirements",
   );
   expect(await holds(turns, "I will wait until you are ready.", director)).toBe(
     false,