@growthub/cli 0.14.3 → 0.14.4

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/globals.css

@@ -9211,6 +9211,14 @@ body.workspace-rail-collapsed .workspace-builder.workspace-lens-page,
 .dm-swarm-body { display: flex; flex-direction: column; min-height: 0; }
 .dm-swarm-cockpit { flex: 1; min-height: 0; overflow-y: auto; padding: 12px 14px 16px; display: flex; flex-direction: column; gap: 10px; }
 .dm-swarm-cockpit-list { display: flex; flex-direction: column; gap: 8px; }
+.dm-ceo-tabs { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 4px; margin: -4px 0 2px; }
+.dm-ceo-tabs button { min-height: 30px; padding: 5px 10px; border: 1px solid #e5e7eb; border-radius: 5px; background: #fff; color: #374151; font-size: 12px; font-weight: 600; cursor: pointer; }
+.dm-ceo-tabs button:hover { border-color: #cbd5e1; color: #111827; }
+.dm-ceo-tabs button.is-active { background: #111827; border-color: #111827; color: #fff; }
+/* CEO fleet list — layout-only grouping; the parent .dm-swarm-cockpit owns the
+   scroll, so this never introduces a second scrollbar. Visible count is capped
+   in the component (CEO_FLEET_VISIBLE_CAP). */
+.dm-ceo-report-list { display: grid; gap: 8px; }
 .dm-swarm-section-row { display: flex; align-items: center; justify-content: space-between; margin-top: 4px; }
 
 /* Run card — surface chrome comes from dm-helper-toolcall in the JSX. */
@@ -9218,6 +9226,9 @@ body.workspace-rail-collapsed .workspace-builder.workspace-lens-page,
 .dm-swarm-card-head { display: flex; align-items: center; gap: 8px; }
 .dm-swarm-card-title { flex: 1; }
 .dm-swarm-card-action { height: 24px; padding: 0 7px; }
+.dm-ceo-card-redirect { opacity: 0; transition: opacity .12s ease, border-color .12s ease, color .12s ease; }
+.dm-swarm-card:hover .dm-ceo-card-redirect,
+.dm-swarm-card:focus-within .dm-ceo-card-redirect { opacity: 1; }
 .dm-swarm-card-meta { display: flex; align-items: center; gap: 10px; }
 .dm-swarm-card-meta .dm-run-console__hint { font-size: 12px; }
 .dm-swarm-card-kind { font-weight: 600; }

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/ceo-agent-teams.js

@@ -0,0 +1,211 @@
+/**
+ * CEO Agent Teams — the atomic, reusable team-configuration layer for the /ceo
+ * surface (CEO_PRIMITIVE_COCKPIT_ROADMAP_V1).
+ *
+ * Distinction this module encodes:
+ *   - FLEET (runtime/oversight) = existing `swarm-workflows` rows, readiness,
+ *     run state, failures, receipts, Background Tasks. UNCHANGED by this module.
+ *   - AGENT TEAMS (atomic configuration) = reusable blueprints describing the
+ *     orchestrator, sub-agent roles, skills, processes, workflow
+ *     responsibilities, and outcome criteria of a swarm.
+ *
+ * This is a PURE module — no React, no fetch, no fs, no writes, no localStorage.
+ * It introduces NO new runtime, executor, API route, PATCH allowlist field, or
+ * object type: Agent Teams live in a governed Data Model object of the EXISTING
+ * `custom` objectType, created through the EXISTING `dataModel.object.create`
+ * helper/apply lane, and they only ever *inform* a `/swarm` proposal — the
+ * server still builds the `agent-swarm-v1` graph, the run still lands in
+ * `swarm-workflows`, and execution still happens through `sandbox-run`.
+ *
+ * An Agent Team record never executes anything.
+ */
+
+export const AGENT_SWARM_TEAMS_OBJECT_ID = "agent-swarm-teams";
+export const AGENT_SWARM_TEAMS_LABEL = "Agent Swarm Teams";
+
+// Visible row columns. "Name" is the capital-N identity column (Data Model grid
+// convention). Array-shaped fields are stored as readable strings so we never
+// fight the row-value contract (no typed arrays in rows).
+export const AGENT_SWARM_TEAMS_COLUMNS = [
+  "id",
+  "Name",
+  "status",
+  "teamPurpose",
+  "orchestratorRole",
+  "orchestratorPrompt",
+  "subAgentRoles",
+  "skills",
+  "processes",
+  "workflowResponsibilities",
+  "outcomeCriteria",
+  "defaultRunLocality",
+  "defaultAdapter",
+  "linkedSwarmWorkflowName",
+  "governanceNotes",
+  "createdAt",
+  "updatedAt",
+];
+
+function clean(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function slugify(value) {
+  return clean(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// One clearly-labeled blueprint row so a freshly-created table shows the shape
+// (and is honestly an example, not live state).
+function blueprintRow() {
+  return {
+    id: "team-research-synthesis",
+    Name: "Example — Research & Synthesis Team",
+    status: "blueprint",
+    teamPurpose: "Reusable blueprint: research a topic and synthesize a cited brief.",
+    orchestratorRole: "Research Lead",
+    orchestratorPrompt: "Decompose the objective into independent research subtasks for the team.",
+    subAgentRoles: "Researcher; Analyst; Synthesizer",
+    skills: "web-research; summarization; critique",
+    processes: "gather → analyze → synthesize",
+    workflowResponsibilities: "Researcher gathers facts; Analyst stress-tests; Synthesizer writes the brief",
+    outcomeCriteria: "A cited brief with risks and a clear recommendation",
+    defaultRunLocality: "local",
+    defaultAdapter: "local-intelligence",
+    linkedSwarmWorkflowName: "",
+    governanceNotes: "Blueprint only — launch through /swarm; the run lands in swarm-workflows and emits receipts.",
+    createdAt: "",
+    updatedAt: "",
+  };
+}
+
+/** The governed Agent Teams object definition (existing `custom` objectType). */
+export function buildAgentSwarmTeamsObject({ includeBlueprint = true } = {}) {
+  return {
+    id: AGENT_SWARM_TEAMS_OBJECT_ID,
+    label: AGENT_SWARM_TEAMS_LABEL,
+    objectType: "custom",
+    columns: AGENT_SWARM_TEAMS_COLUMNS.slice(),
+    rows: includeBlueprint ? [blueprintRow()] : [],
+    binding: { mode: "manual", source: AGENT_SWARM_TEAMS_LABEL },
+  };
+}
+
+/**
+ * A governed proposal that CREATES the Agent Teams table through the EXISTING
+ * `dataModel.object.create` helper/apply lane. No new proposal type, no new
+ * objectType — objectType stays `custom`.
+ */
+export function buildCreateAgentTeamsProposal() {
+  return {
+    type: "dataModel.object.create",
+    affectedField: "dataModel",
+    payload: { object: buildAgentSwarmTeamsObject({ includeBlueprint: true }) },
+    rationale: "Create the governed Agent Swarm Teams table — reusable swarm blueprints (config, not runtime).",
+  };
+}
+
+export function findAgentTeamsObject(workspaceConfig) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  return objects.find((o) => o?.id === AGENT_SWARM_TEAMS_OBJECT_ID) || null;
+}
+
+export function findAgentTeams(workspaceConfig) {
+  const object = findAgentTeamsObject(workspaceConfig);
+  const rows = Array.isArray(object?.rows) ? object.rows : [];
+  const seen = new Set();
+  return rows
+    .filter((row) => row && clean(row.Name))
+    .map((row, index) => {
+      const name = clean(row.Name);
+      // Stable atomic identity: explicit id, else a slug of Name, else index —
+      // de-duplicated so two same-named blueprints never collide as React keys
+      // (the same fix applied to fleet reports).
+      let teamId = clean(row.id) || slugify(name) || `team-${index + 1}`;
+      while (seen.has(teamId)) teamId = `${teamId}-${index + 1}`;
+      seen.add(teamId);
+      return {
+        teamId,
+        name,
+        status: clean(row.status) || "blueprint",
+        teamPurpose: clean(row.teamPurpose),
+        orchestratorRole: clean(row.orchestratorRole),
+        orchestratorPrompt: clean(row.orchestratorPrompt),
+        subAgentRoles: clean(row.subAgentRoles),
+        skills: clean(row.skills),
+        processes: clean(row.processes),
+        workflowResponsibilities: clean(row.workflowResponsibilities),
+        outcomeCriteria: clean(row.outcomeCriteria),
+        defaultRunLocality: clean(row.defaultRunLocality),
+        defaultAdapter: clean(row.defaultAdapter),
+        linkedSwarmWorkflowName: clean(row.linkedSwarmWorkflowName),
+        governanceNotes: clean(row.governanceNotes),
+      };
+    });
+}
+
+/**
+ * Project the Agent Teams configuration layer for the cockpit. Pure.
+ *   { present, count, teams[], canCreate }
+ */
+export function deriveAgentTeamsState({ workspaceConfig } = {}) {
+  const object = findAgentTeamsObject(workspaceConfig);
+  const teams = findAgentTeams(workspaceConfig);
+  return {
+    objectId: AGENT_SWARM_TEAMS_OBJECT_ID,
+    present: Boolean(object),
+    count: teams.length,
+    teams,
+    // The table is created through the governed create lane when absent.
+    canCreate: !object,
+  };
+}
+
+function joinAgents(subAgentRoles) {
+  return clean(subAgentRoles)
+    .split(/[;,\n]/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Build the /swarm composer seed text from an Agent Team blueprint. This is
+ * PROPOSE-ONLY seed copy: it prefills the helper composer so the user proposes
+ * a governed swarm "from this blueprint". The model + server still produce the
+ * proposal and build the agent-swarm-v1 graph; nothing here executes.
+ */
+export function buildSwarmIntentFromTeam(team) {
+  if (!team) return "Propose a governed agent swarm:";
+  const agents = joinAgents(team.subAgentRoles);
+  const target = [
+    team.defaultAdapter ? `adapter ${team.defaultAdapter}` : "",
+    team.defaultRunLocality ? `${team.defaultRunLocality} run target` : "",
+  ].filter(Boolean).join(", ");
+  // Carry the full atomic configuration forward so the blueprint is a true
+  // configuration inversion of the swarm — still propose-only seed copy; the
+  // server builds the agent-swarm-v1 graph and nothing executes here.
+  const parts = [
+    `Propose a governed agent swarm from the Agent Team blueprint "${team.name}".`,
+    team.teamPurpose ? `Objective: ${team.teamPurpose}` : "",
+    team.orchestratorRole || team.orchestratorPrompt
+      ? `Orchestrator${team.orchestratorRole ? ` (${team.orchestratorRole})` : ""}: ${team.orchestratorPrompt || "plan the work for the team"}.`
+      : "",
+    agents.length ? `Sub-agents: ${agents.join(", ")}.` : "",
+    team.skills ? `Skills: ${team.skills}.` : "",
+    team.processes ? `Process: ${team.processes}.` : "",
+    team.workflowResponsibilities ? `Workflow responsibilities: ${team.workflowResponsibilities}.` : "",
+    team.outcomeCriteria ? `Outcome criteria: ${team.outcomeCriteria}.` : "",
+    target ? `Preferred execution target: ${target}.` : "",
+    team.governanceNotes ? `Governance notes: ${team.governanceNotes}.` : "",
+  ];
+  return parts.filter(Boolean).join(" ");
+}
+
+export function summarizeTeam(team) {
+  const agents = joinAgents(team?.subAgentRoles).length;
+  return [
+    team?.orchestratorRole ? `orchestrator: ${team.orchestratorRole}` : null,
+    agents ? `${agents} sub-agent${agents === 1 ? "" : "s"}` : null,
+  ].filter(Boolean).join(" · ");
+}
+
+export default deriveAgentTeamsState;

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/ceo-bootstrap-console.js

@@ -0,0 +1,325 @@
+/**
+ * CEO bootstrap projection — the first-use closed-loop harness for the CEO
+ * cockpit (CEO_PRIMITIVE_COCKPIT_ROADMAP_V1, follow-up to R1/R2).
+ *
+ * This is a PURE deriver — no React, no fetch, no fs, no config writes, no
+ * localStorage. It derives TWO modes from workspace state alone:
+ *
+ *   - "bootstrap"   — shown until the workspace has a CEO completion marker.
+ *                     A state-derived smoke-test checklist that proves every
+ *                     CEO primitive end-to-end (orchestrate → create → test →
+ *                     launch → observe → review → govern → complete).
+ *   - "operational" — the existing fleet cockpit, after completion.
+ *
+ * The mode comes from a completion marker that lives in workspace CONFIG (a
+ * field on the existing well-known workspace-helper sandbox row), NEVER a
+ * browser flag. It introduces no new object type, no new API, no new PATCH
+ * field, and no new execution path: the checklist is a projection over the
+ * existing swarm fleet + receipt stream, and completion is stamped through the
+ * existing helper/apply lane via the `ceo.bootstrap.complete` proposal.
+ *
+ * Completion is gated on config-provable evidence — a governed swarm workflow
+ * that is ready AND has a COMPLETED run on its row — so "done" means the loop
+ * actually ran, not that a button was clicked.
+ */
+
+import { deriveCeoCockpit } from "./ceo-cockpit-console.js";
+import { deriveHelperWidgetCausationState } from "./workspace-swarm-proposal.js";
+
+// Well-known anchors — the same constants the swarm/helper lanes use. Kept
+// local (they are module-private upstream) so this stays a pure leaf module.
+export const WORKSPACE_HELPER_SANDBOX_OBJECT_ID = "workspace-helper-sandbox";
+export const WORKSPACE_HELPER_ROW_NAME = "workspace-helper";
+export const CEO_BOOTSTRAP_COMPLETE_PROPOSAL_TYPE = "ceo.bootstrap.complete";
+export const CEO_BOOTSTRAP_MARKER_FIELD = "ceoBootstrapCompletedAt";
+export const CEO_BOOTSTRAP_BY_FIELD = "ceoBootstrapCompletedBy";
+export const CEO_BOOTSTRAP_RECEIPT_FIELD = "ceoBootstrapReceiptId";
+
+function clean(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+// Locate the well-known helper row (and its object) for marker read/write.
+function findHelperRowLocation(workspaceConfig) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects)
+    ? workspaceConfig.dataModel.objects
+    : [];
+  const objectIndex = objects.findIndex((o) => o?.id === WORKSPACE_HELPER_SANDBOX_OBJECT_ID);
+  if (objectIndex < 0) return { objectIndex: -1, rowIndex: -1, object: null, row: null };
+  const object = objects[objectIndex];
+  const rows = Array.isArray(object?.rows) ? object.rows : [];
+  let rowIndex = rows.findIndex((r) => clean(r?.Name) === WORKSPACE_HELPER_ROW_NAME);
+  if (rowIndex < 0 && rows.length > 0) rowIndex = 0;
+  return { objectIndex, rowIndex, object, row: rowIndex >= 0 ? rows[rowIndex] : null };
+}
+
+// Read the completion marker from config (the single source of mode truth).
+function readCompletion(workspaceConfig) {
+  const { object, row } = findHelperRowLocation(workspaceConfig);
+  const at = clean(row?.[CEO_BOOTSTRAP_MARKER_FIELD]);
+  if (!row || !at) return null;
+  return {
+    objectId: object?.id || WORKSPACE_HELPER_SANDBOX_OBJECT_ID,
+    rowName: clean(row?.Name) || WORKSPACE_HELPER_ROW_NAME,
+    completedAt: at,
+    completedBy: clean(row?.[CEO_BOOTSTRAP_BY_FIELD]) || null,
+    receiptId: clean(row?.[CEO_BOOTSTRAP_RECEIPT_FIELD]) || null,
+  };
+}
+
+// A receipt counts as governance evidence when it is an execution proof or a
+// governed apply that succeeded — the same lane vocabulary the cockpit uses.
+function hasGovernanceEvidence(receipts) {
+  return (Array.isArray(receipts) ? receipts : []).some((r) => {
+    if (!r || typeof r !== "object") return false;
+    if (r.outcomeStatus === "blocked") return false;
+    return r.lane === "execution-proof" || r.lane === "governed-proposal";
+  });
+}
+
+function item(id, label, status, { guidance = "", evidenceRefs = [], nextAction = null } = {}) {
+  return { id, label, status, guidance, evidenceRefs, nextAction };
+}
+
+// Choose the workflow the checklist follows end-to-end: prefer one that
+// completed, else one that ran, else one that is ready, else the first.
+function pickFocus(reports) {
+  return (
+    reports.find((r) => r.state === "completed") ||
+    reports.find((r) => r.lastRun) ||
+    reports.find((r) => r.readiness?.ready) ||
+    reports[0] ||
+    null
+  );
+}
+
+function openArtifactAction(report, label) {
+  if (!report?.nextAction?.artifact) return null;
+  return { kind: "open", label, artifact: report.nextAction.artifact };
+}
+
+/**
+ * Derive the CEO bootstrap state from workspace config (+ optional receipts).
+ * Pure. See module header for the return shape.
+ */
+export function deriveCeoBootstrapState({ workspaceConfig, receipts = [] } = {}) {
+  const completionRef = readCompletion(workspaceConfig);
+  const cockpit = deriveCeoCockpit({ workspaceConfig, receipts });
+  const reports = cockpit.reports;
+  const helperState = deriveHelperWidgetCausationState(workspaceConfig);
+  const helperReady = helperState.ready === true;
+  const focus = pickFocus(reports);
+  const ran = Boolean(focus?.lastRun);
+  const completedRun = focus?.lastRun?.status === "completed";
+  const failedRun = focus?.lastRun?.status === "failed";
+  const governanceEvidence = hasGovernanceEvidence(receipts) || ran;
+
+  const checklist = [];
+
+  // 1 — Mental model (informational primer; satisfied by reading the loop).
+  checklist.push(item("mental-model", "Understand the CEO loop", "complete", {
+    guidance: "You're the CEO: orchestrate a swarm, validate it, launch it, observe truthful telemetry, then review the outcome.",
+  }));
+
+  // 2 — Governed swarm workflow exists (helper must be live to create one).
+  if (reports.length > 0) {
+    checklist.push(item("swarm-workflow", "Create your first agent swarm", "complete", {
+      guidance: "A governed swarm workflow is present in the fleet.",
+      evidenceRefs: focus?.name ? [focus.name] : [],
+    }));
+  } else if (helperReady) {
+    checklist.push(item("swarm-workflow", "Create your first agent swarm", "ready", {
+      guidance: "Propose your first agent swarm with /swarm — review and apply it to create the governed workflow.",
+      nextAction: { kind: "seed-swarm", label: "Propose a swarm" },
+    }));
+  } else {
+    checklist.push(item("swarm-workflow", "Create your first agent swarm", "blocked", {
+      guidance: `Bring the workspace helper online first. ${helperState.guidance}`,
+      nextAction: { kind: "setup", label: "Open Setup" },
+    }));
+  }
+
+  // 3 — Execution readiness (the existing eligibility gate).
+  if (!focus) {
+    checklist.push(item("readiness", "Validate execution readiness", "pending", {
+      guidance: "Create a swarm workflow first.",
+    }));
+  } else if (focus.readiness.ready) {
+    checklist.push(item("readiness", "Validate execution readiness", "complete", {
+      guidance: `Execution target ready (${focus.readiness.adapter}${focus.readiness.agentHost ? ` · ${focus.readiness.agentHost}` : ""}).`,
+      evidenceRefs: [focus.readiness.adapter].filter(Boolean),
+    }));
+  } else {
+    checklist.push(item("readiness", "Validate execution readiness", "blocked", {
+      guidance: focus.readiness.guidance,
+      nextAction: openArtifactAction(focus, "Open to fix"),
+    }));
+  }
+
+  // 4 — Launch through the existing Background Tasks (sandbox-run).
+  if (!focus) {
+    checklist.push(item("launch", "Launch through Background Tasks", "pending", {
+      guidance: "Create a swarm workflow first.",
+    }));
+  } else if (ran) {
+    checklist.push(item("launch", "Launch through Background Tasks", "complete", {
+      guidance: "Launched at least once via the existing sandbox-run executor.",
+      evidenceRefs: focus.lastRun.runId ? [focus.lastRun.runId] : [],
+    }));
+  } else if (focus.readiness.ready) {
+    checklist.push(item("launch", "Launch through Background Tasks", "ready", {
+      guidance: "Open the workflow and press Run — execution stays in Background Tasks.",
+      nextAction: openArtifactAction(focus, "Open to launch"),
+    }));
+  } else {
+    checklist.push(item("launch", "Launch through Background Tasks", "pending", {
+      guidance: "Resolve execution readiness first.",
+    }));
+  }
+
+  // 5 — Observe truthful telemetry (a persisted run record exists).
+  if (ran) {
+    checklist.push(item("observe", "Observe truthful telemetry", "complete", {
+      guidance: "A run record is persisted — tokens/tools show truthfully (— when the adapter reported nothing).",
+      evidenceRefs: focus.lastRun.runId ? [focus.lastRun.runId] : [],
+    }));
+  } else {
+    checklist.push(item("observe", "Observe truthful telemetry", "pending", {
+      guidance: "Launch the swarm to produce a run record.",
+    }));
+  }
+
+  // 6 — Review the outcome (completed vs failed — failure is not success).
+  if (!ran) {
+    checklist.push(item("review", "Review the outcome", "pending", {
+      guidance: "Launch the swarm first.",
+    }));
+  } else if (completedRun) {
+    checklist.push(item("review", "Review the outcome", "complete", {
+      guidance: "The run completed successfully.",
+    }));
+  } else if (failedRun) {
+    checklist.push(item("review", "Review the outcome", "blocked", {
+      guidance: "Last run failed — review the transcript and re-run before completing setup.",
+      nextAction: openArtifactAction(focus, "Open to review"),
+    }));
+  } else {
+    checklist.push(item("review", "Review the outcome", "pending", {
+      guidance: "The run is still in progress — open it to watch.",
+    }));
+  }
+
+  // 7 — Confirm governance receipts exist.
+  checklist.push(item("governance", "Confirm governance receipts", governanceEvidence ? "complete" : "pending", {
+    guidance: governanceEvidence
+      ? "Governed activity is recorded in the agent-outcomes receipt stream."
+      : "Receipts appear once you launch a run or apply a governed proposal.",
+  }));
+
+  // 8 — Mark CEO setup complete (the only mutation; goes through helper/apply).
+  const prereqIds = ["swarm-workflow", "readiness", "launch", "review"];
+  const prereqsMet = prereqIds.every(
+    (id) => checklist.find((c) => c.id === id)?.status === "complete"
+  );
+  if (completionRef) {
+    checklist.push(item("complete", "Mark CEO setup complete", "complete", {
+      guidance: "CEO setup is complete for this workspace.",
+      evidenceRefs: [completionRef.completedAt],
+    }));
+  } else if (prereqsMet) {
+    checklist.push(item("complete", "Mark CEO setup complete", "ready", {
+      guidance: "You've proven the full CEO loop — lock it in. This checklist then disappears for this workspace.",
+      nextAction: { kind: "mark-complete", label: "Complete" },
+    }));
+  } else {
+    checklist.push(item("complete", "Mark CEO setup complete", "pending", {
+      guidance: "Finish the steps above to unlock completion.",
+    }));
+  }
+
+  // The single next move — first actionable (ready/blocked) item in order.
+  const primaryItem = checklist.find(
+    (c) => (c.status === "ready" || c.status === "blocked") && c.nextAction
+  );
+  const primaryAction = primaryItem
+    ? { itemId: primaryItem.id, ...primaryItem.nextAction }
+    : null;
+
+  const completedCount = checklist.filter((c) => c.status === "complete").length;
+
+  return {
+    title: "CEO Cockpit",
+    mode: completionRef ? "operational" : "bootstrap",
+    completed: Boolean(completionRef),
+    completionRef,
+    checklist,
+    primaryAction,
+    progress: { completed: completedCount, total: checklist.length },
+    focus: focus ? { objectId: focus.objectId, name: focus.name } : null,
+  };
+}
+
+/**
+ * Governed completion builder — stamps the CEO bootstrap marker onto the
+ * well-known helper row in `dataModel`. Pure (returns a new config; writes
+ * nothing). Used by the helper/apply `ceo.bootstrap.complete` lane.
+ *
+ * Refuses to stamp unless the bootstrap prerequisites are config-provably met
+ * (a ready swarm with a completed run) — so the marker is real evidence, not a
+ * client assertion.
+ *
+ * @returns {{ ok: boolean, config: object, error?: string }}
+ */
+export function buildCeoBootstrapCompletion({
+  workspaceConfig,
+  completedAt,
+  completedBy = "user",
+  receiptId = null,
+} = {}) {
+  const existing = readCompletion(workspaceConfig);
+  if (existing) {
+    // Idempotent — already complete, nothing to change.
+    return { ok: true, config: workspaceConfig };
+  }
+
+  const state = deriveCeoBootstrapState({ workspaceConfig });
+  const completeItem = state.checklist.find((c) => c.id === "complete");
+  if (!completeItem || completeItem.status !== "ready") {
+    const blocking = state.checklist
+      .filter((c) => ["swarm-workflow", "readiness", "launch", "review"].includes(c.id))
+      .filter((c) => c.status !== "complete")
+      .map((c) => c.label);
+    return {
+      ok: false,
+      config: workspaceConfig,
+      error: `CEO bootstrap prerequisites not met: ${blocking.join("; ") || "incomplete"}`,
+    };
+  }
+
+  const { objectIndex, rowIndex } = findHelperRowLocation(workspaceConfig);
+  if (objectIndex < 0 || rowIndex < 0) {
+    return { ok: false, config: workspaceConfig, error: "workspace helper sandbox row not found" };
+  }
+
+  const stampedAt = clean(completedAt) || new Date().toISOString();
+  const objects = workspaceConfig.dataModel.objects.map((object, oi) => {
+    if (oi !== objectIndex) return object;
+    const rows = object.rows.map((row, ri) => {
+      if (ri !== rowIndex) return row;
+      return {
+        ...row,
+        [CEO_BOOTSTRAP_MARKER_FIELD]: stampedAt,
+        [CEO_BOOTSTRAP_BY_FIELD]: clean(completedBy) || "user",
+        ...(clean(receiptId) ? { [CEO_BOOTSTRAP_RECEIPT_FIELD]: clean(receiptId) } : {}),
+      };
+    });
+    return { ...object, rows };
+  });
+
+  return {
+    ok: true,
+    config: { ...workspaceConfig, dataModel: { ...workspaceConfig.dataModel, objects } },
+  };
+}
+
+export default deriveCeoBootstrapState;