@growthub/cli 0.14.2 → 0.14.4

package/assets/worker-kits/growthub-custom-workspace-starter-v1/SKILL.md

@@ -29,7 +29,9 @@ helpers:
   - path: helpers/check-self-improving-health.sh
     verb: check-self-improving-health
     description: Validate self-improving workspace primitives and proposal dirs.
-subSkills: []
+subSkills:
+  - name: governed-workspace-mutation
+    path: skills/governed-workspace-mutation/SKILL.md
 mcpTools: []
 ---
 
@@ -44,7 +46,7 @@ Every Growthub governed Workspace is materialised from this kit. The kit ships t
 3. **`templates/project.md`** — session-memory template. On `growthub starter init` and `growthub starter import-*`, the CLI copies this to `.growthub-fork/project.md` so every fork starts with an append-only editing history alongside the machine-readable `trace.jsonl`.
 4. **`templates/self-eval.md`** — self-evaluation pattern. Describes the generate → render → evaluate → retry (≤3) loop that mirrors the Fork Sync Agent's preview → apply → trace lifecycle.
 5. **`helpers/`** — safe shell tool layer. Scripts an agent calls via one shell invocation instead of reconstructing raw commands. Populated per fork; the baseline ships conventions only.
-6. **`skills/`** — nested sub-skill convention. Each sub-directory is a full `SKILL.md`-addressable sub-skill that a parent agent can spawn in parallel for heavy or narrow tasks.
+6. **`skills/`** — nested sub-skill convention. Each sub-directory is a full `SKILL.md`-addressable sub-skill that a parent agent can spawn in parallel for heavy or narrow tasks. The baseline ships [`skills/governed-workspace-mutation/SKILL.md`](./skills/governed-workspace-mutation/SKILL.md) — the runtime-verified contract card for the two canonical workspace calls (`PATCH /api/workspace`, `POST /api/workspace/sandbox-run`). **Read it before any workspace-configuration mutation or sandbox execution.**
 
 ## When to use this skill
 

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/agent-outcomes/route.js

@@ -0,0 +1,85 @@
+/**
+ * GET /api/workspace/agent-outcomes
+ *
+ * The governance cockpit data model (Agent Outcome Loop V1 — contract:
+ * `@growthub/api-contract/workspace-outcome::AgentOutcomesResponse`).
+ *
+ * Returns the unified receipt stream (newest first, bounded) that every
+ * mutation lane emits — direct PATCH, preflight rejections, sandbox runs,
+ * workflow publishes, helper applies — plus an always-recomputed governance
+ * summary derived from the live config:
+ *
+ *   - blocked policy/gate attempts
+ *   - successful publishes
+ *   - drafts waiting for a test
+ *   - drafts tested but not published
+ *   - live workflow rows whose last run failed
+ *   - live workflow rows with no recorded run at all
+ *   - helper applies
+ *
+ * Read-only. This is how an operator manages a workspace full of agents
+ * without reading logs, and how the next agent inherits context: read the
+ * stream, cite receiptIds, continue from `nextActions` / `rollbackRef`.
+ */
+
+import { NextResponse } from "next/server";
+import { readWorkspaceConfig } from "@/lib/workspace-config";
+import { AGENT_OUTCOMES_SOURCE_ID, readOutcomeReceipts } from "@/lib/workspace-outcome-receipts";
+
+function hasValue(v) {
+  return Boolean(String(v ?? "").trim());
+}
+
+function deriveRowCounters(workspaceConfig) {
+  const counters = {
+    draftsAwaitingTest: 0,
+    draftsTestedNotPublished: 0,
+    liveRowsWithFailedLastRun: 0,
+    liveRowsWithoutProof: 0
+  };
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  for (const object of objects) {
+    if (object?.objectType !== "sandbox-environment") continue;
+    for (const row of Array.isArray(object.rows) ? object.rows : []) {
+      const hasDraft = hasValue(row?.orchestrationDraftConfig) || hasValue(row?.orchestrationDraftGraph);
+      const attested = row?.orchestrationDraftTestPassed === true
+        || String(row?.orchestrationDraftTestPassed ?? "") === "true";
+      if (hasDraft && !attested) counters.draftsAwaitingTest += 1;
+      if (hasDraft && attested) counters.draftsTestedNotPublished += 1;
+      const isLive = String(row?.lifecycleStatus ?? "").trim().toLowerCase() === "live";
+      if (isLive && String(row?.status ?? "") === "failed") counters.liveRowsWithFailedLastRun += 1;
+      if (isLive && !hasValue(row?.lastRunId)) counters.liveRowsWithoutProof += 1;
+    }
+  }
+  return counters;
+}
+
+async function GET(request) {
+  const { searchParams } = new URL(request.url);
+  const limitRaw = Number(searchParams.get("limit") || 100);
+  const limit = Number.isFinite(limitRaw) ? Math.min(Math.max(1, limitRaw), 200) : 100;
+
+  const receipts = await readOutcomeReceipts(limit);
+  let workspaceConfig = null;
+  try {
+    workspaceConfig = await readWorkspaceConfig();
+  } catch {
+    workspaceConfig = null;
+  }
+
+  const summary = {
+    blockedAttempts: receipts.filter((r) => r?.outcomeStatus === "blocked").length,
+    publishes: receipts.filter((r) => r?.kind === "workflow-publish" && r?.outcomeStatus === "published").length,
+    helperApplies: receipts.filter((r) => r?.kind === "helper-apply").length,
+    ...deriveRowCounters(workspaceConfig)
+  };
+
+  return NextResponse.json({
+    ok: true,
+    sourceId: AGENT_OUTCOMES_SOURCE_ID,
+    receipts,
+    summary
+  });
+}
+
+export { GET };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/apps/route.js

@@ -0,0 +1,187 @@
+/**
+ * GET /api/workspace/apps
+ *
+ * Governed Application Control Plane V1 — the fleet read surface (contract:
+ * `@growthub/api-contract/workspace-apps::WorkspaceAppsResponse`).
+ *
+ * Returns, read-only and secret-free:
+ *
+ *   - `apps[]`      — every application registered as a governed row of the
+ *                     `workspace-app-registry` Data Model object: resolved
+ *                     links (dashboards / workflows / data sources / APIs),
+ *                     health rollup with computed blockers, the single next
+ *                     action (with an href into the real surface), and the
+ *                     machine-readable agent assignment packet.
+ *   - `detected[]`  — app surfaces detected on the artifact's own filesystem
+ *                     (same probe heuristics as the CLI's `workspace surface
+ *                     list`, bridged into the runtime so registration never
+ *                     requires a separate tool). Detection is advisory: an
+ *                     app becomes GOVERNED only when a human/agent registers
+ *                     it as a row via the normal PATCH lane.
+ *   - `lens`        — the Fleet lens state (same deriver the Workspace Lens
+ *                     panel renders), so humans and agents read one truth.
+ *   - `summary`     — fleet counters.
+ *
+ * Authority invariants: GET only; mutations flow through the existing
+ * governed routes; this route never throws on partial/absent config.
+ */
+
+import { NextResponse } from "next/server";
+import fsSync from "node:fs";
+import path from "node:path";
+import {
+  describePersistenceMode,
+  readWorkspaceConfig,
+  readWorkspaceSourceRecords
+} from "@/lib/workspace-config";
+import { readAdapterConfig } from "@/lib/adapters/env";
+import {
+  APP_REGISTRY_OBJECT_ID,
+  buildAppAssignmentPacket,
+  deriveAppHealth,
+  deriveAppNextAction,
+  listAppSurfaceRows,
+  summarizeFleet
+} from "@/lib/workspace-app-registry";
+import {
+  deriveDeployLensState,
+  deriveFleetLensState,
+  deriveRuntimeDurability
+} from "@/lib/workspace-activation";
+
+/** Same safe runtime descriptor the swarm-condition route assembles. */
+function safeRuntime(warnings) {
+  const runtime = { persistenceMode: "", persistenceAdapter: null, allowFsWrite: false, nangoConfigured: false, deploy: {} };
+  try {
+    const persistence = describePersistenceMode();
+    runtime.persistenceMode = persistence.mode;
+    runtime.allowFsWrite = persistence.mode === "filesystem" && persistence.canSave === true;
+    const adapter = readAdapterConfig();
+    runtime.persistenceAdapter = persistence.mode === "database" ? (adapter.dataAdapter || null) : null;
+    runtime.nangoConfigured = Boolean(adapter?.nango?.hasSecretKey);
+    runtime.deploy = { target: adapter.deployTarget || "" };
+  } catch (error) {
+    warnings.push(`Failed to read runtime descriptor: ${error?.message || "unknown error"}`);
+  }
+  return runtime;
+}
+
+// Mirrors the CLI probe (cli/src/commands/workspace-surface.ts) so detection
+// lives inside the artifact too — the bridge roadmap Item 4 called for.
+const KNOWN_APP_DIRS = ["apps/workspace", "apps/agency-portal", "apps/portal", "studio", "app", "src"];
+
+function detectFramework(absPath) {
+  try {
+    const entries = fsSync.readdirSync(absPath);
+    if (entries.some((e) => e.startsWith("next.config."))) return "nextjs";
+    if (entries.some((e) => e.startsWith("vite.config."))) return "vite";
+  } catch {
+    /* unreadable */
+  }
+  return "unknown";
+}
+
+function looksLikeAppSurface(absPath) {
+  try {
+    const has = (rel) => fsSync.existsSync(path.join(absPath, rel));
+    return has("package.json") || has("index.html") || has("app") || has("pages") || has("src");
+  } catch {
+    return false;
+  }
+}
+
+/** Read-only filesystem probe of the artifact root. Never throws. */
+function detectAppSurfaces(warnings) {
+  const detected = [];
+  try {
+    // The workspace app runs from <artifact>/apps/workspace.
+    const artifactRoot = path.resolve(process.cwd(), "..", "..");
+    const candidates = new Set(KNOWN_APP_DIRS);
+    const appsDir = path.join(artifactRoot, "apps");
+    if (fsSync.existsSync(appsDir)) {
+      for (const entry of fsSync.readdirSync(appsDir, { withFileTypes: true })) {
+        if (entry.isDirectory()) candidates.add(`apps/${entry.name}`);
+      }
+    }
+    for (const rel of Array.from(candidates).sort()) {
+      const abs = path.join(artifactRoot, rel);
+      if (!fsSync.existsSync(abs) || !fsSync.statSync(abs).isDirectory()) continue;
+      if (!looksLikeAppSurface(abs)) continue;
+      let packageName;
+      try {
+        packageName = JSON.parse(fsSync.readFileSync(path.join(abs, "package.json"), "utf8")).name;
+      } catch {
+        packageName = undefined;
+      }
+      detected.push({
+        name: rel.split("/").pop(),
+        relPath: rel,
+        framework: detectFramework(abs),
+        hasEnvExample: fsSync.existsSync(path.join(abs, ".env.example")),
+        hasVercelJson: fsSync.existsSync(path.join(abs, "vercel.json")),
+        hasGrowthubConfig: fsSync.existsSync(path.join(abs, "growthub.config.json")),
+        ...(packageName ? { packageName } : {})
+      });
+    }
+  } catch (error) {
+    warnings.push(`Surface detection failed: ${error?.message || "unknown error"}`);
+  }
+  return detected;
+}
+
+async function GET() {
+  const warnings = [];
+
+  let workspaceConfig = {};
+  try {
+    workspaceConfig = (await readWorkspaceConfig()) || {};
+  } catch (error) {
+    warnings.push(`Failed to read workspace config: ${error?.message || "unknown error"}`);
+  }
+  let workspaceSourceRecords = {};
+  try {
+    workspaceSourceRecords = (await readWorkspaceSourceRecords()) || {};
+  } catch {
+    workspaceSourceRecords = {};
+  }
+
+  const runtime = safeRuntime(warnings);
+  const metadataGraph = { runtime };
+  const lensInput = { workspaceConfig, workspaceSourceRecords, metadataGraph };
+  const dur = deriveRuntimeDurability(metadataGraph);
+  const runtimeFlags = {
+    durable: dur.durable,
+    readOnly: dur.readOnly,
+    deployReady: deriveDeployLensState(lensInput).complete
+  };
+
+  const apps = listAppSurfaceRows(workspaceConfig).map((row) => {
+    const health = deriveAppHealth(workspaceConfig, workspaceSourceRecords, row, runtimeFlags);
+    return {
+      appId: String(row.appId || row.Name || "").trim(),
+      name: String(row.Name || "").trim(),
+      surfacePath: String(row.surfacePath || "").trim() || null,
+      framework: String(row.framework || "").trim() || null,
+      owner: String(row.owner || "").trim() || null,
+      environment: String(row.environment || "").trim() || null,
+      deployTarget: String(row.deployTarget || "").trim() || null,
+      registryHref: `/data-model?object=${APP_REGISTRY_OBJECT_ID}`,
+      health: { status: health.status, blockers: health.blockers, linkedCount: health.linkedCount },
+      links: health.links,
+      nextAction: deriveAppNextAction(row, health),
+      assignment: buildAppAssignmentPacket(workspaceConfig, workspaceSourceRecords, row, runtimeFlags)
+    };
+  });
+
+  return NextResponse.json({
+    ok: true,
+    registryObjectId: APP_REGISTRY_OBJECT_ID,
+    apps,
+    detected: detectAppSurfaces(warnings),
+    lens: deriveFleetLensState(lensInput),
+    summary: summarizeFleet(apps),
+    ...(warnings.length ? { warnings } : {})
+  });
+}
+
+export { GET };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/helper/apply/route.js

@@ -35,6 +35,8 @@ import {
   writeWorkspaceSourceRecords,
   describePersistenceMode,
 } from "@/lib/workspace-config";
+import { appendOutcomeReceipt } from "@/lib/workspace-outcome-receipts";
+import { buildAppScopeViolation } from "@/lib/workspace-app-registry";
 import {
   applyProposalToConfig,
   validateProposalForApply,
@@ -54,6 +56,10 @@ import {
   findSwarmRunRows,
   summarizeSwarmRunProposal,
 } from "@/lib/workspace-swarm-proposal";
+import {
+  CEO_BOOTSTRAP_COMPLETE_PROPOSAL_TYPE,
+  buildCeoBootstrapCompletion,
+} from "@/lib/ceo-bootstrap-console";
 
 const HELPER_APPLY_SOURCE_KEY = "helper:apply:receipts";
 
@@ -204,6 +210,23 @@ function normalizeSwarmRunProposal(proposal, workspaceConfig) {
 }
 
 async function POST(request) {
+  // helper/apply is the OPERATOR lane (human-reviewed proposals). It is not
+  // available under an app scope — app-scoped agents use preflight + scoped
+  // PATCH + sandbox-run + workflow/publish. Advertised truthfully in
+  // AppAssignmentPacket.operatorOnlyRoutes.
+  const scopedHeader = request.headers.get("x-growthub-app-scope");
+  if (scopedHeader && scopedHeader.trim()) {
+    const violation = buildAppScopeViolation(scopedHeader.trim(), "route_operator_only",
+      ["POST /api/workspace/helper/apply"],
+      "helper/apply is the human-reviewed operator lane; app-scoped agents mutate via preflight + scoped PATCH", null);
+    await appendOutcomeReceipt({
+      kind: "helper-apply", lane: "governed-proposal", outcomeStatus: "blocked",
+      appId: scopedHeader.trim(),
+      summary: "helper/apply rejected (422 app scope): operator-only lane",
+      nextActions: violation.repairPlan
+    });
+    return NextResponse.json(violation, { status: 422 });
+  }
   let body;
   try {
     body = await request.json();
@@ -248,8 +271,14 @@ async function POST(request) {
   );
   const resolverProposals = normalizedProposals.filter((p) => p?.type === RESOLVER_PROPOSAL_TYPE);
   const swarmProposals = normalizedProposals.filter((p) => SWARM_PROPOSAL_TYPES.includes(p?.type));
+  const ceoBootstrapProposals = normalizedProposals.filter(
+    (p) => p?.type === CEO_BOOTSTRAP_COMPLETE_PROPOSAL_TYPE
+  );
   const configProposals = normalizedProposals.filter(
-    (p) => p?.type !== RESOLVER_PROPOSAL_TYPE && !SWARM_PROPOSAL_TYPES.includes(p?.type)
+    (p) =>
+      p?.type !== RESOLVER_PROPOSAL_TYPE &&
+      !SWARM_PROPOSAL_TYPES.includes(p?.type) &&
+      p?.type !== CEO_BOOTSTRAP_COMPLETE_PROPOSAL_TYPE
   );
 
   for (const proposal of resolverProposals) {
@@ -291,6 +320,28 @@ async function POST(request) {
     });
   }
 
+  // CEO bootstrap lane — stamps the "CEO setup complete" marker onto the
+  // well-known workspace-helper sandbox row in the EXISTING dataModel patch
+  // field. The builder refuses unless the loop is config-provably done (a
+  // ready swarm with a completed run), so completion is evidence, not a
+  // client assertion. No new object, no execution.
+  for (const proposal of ceoBootstrapProposals) {
+    const result = buildCeoBootstrapCompletion({
+      workspaceConfig: workingConfig,
+      completedAt: appliedAt,
+      completedBy: reviewedBy || "user",
+    });
+    if (!result.ok) {
+      skipped.push({ proposal, reason: result.error || "CEO bootstrap not ready to complete" });
+      continue;
+    }
+    workingConfig = result.config;
+    applied.push({
+      ...buildApplyReceipt({ ...proposal, affectedField: "dataModel" }, appliedAt, reviewedBy, sessionId),
+      summary: "CEO setup marked complete",
+    });
+  }
+
   for (const proposal of configProposals) {
     if (
       !proposal ||
@@ -516,6 +567,23 @@ async function POST(request) {
     if (row && Array.isArray(row.messages)) messagesAfterApply = row.messages;
   }
 
+  // Agent Outcome Loop V1: the helper lane is GOVERNED-PROPOSAL — privileged
+  // (human-reviewed, server-built payloads), never an unlabelled bypass. It
+  // emits the same canonical receipt class as every other mutation lane, so
+  // the cockpit sees one stream.
+  await appendOutcomeReceipt({
+    kind: "helper-apply",
+    lane: "governed-proposal",
+    outcomeStatus: applied.length > 0 ? "published" : "failed",
+    actor: reviewedBy || "operator",
+    changedFields: Array.from(new Set(mutatingApplied.map((r) => r.affectedField))),
+    objectRefs: threadId ? [{ objectId: "helper-threads", rowName: threadId }] : undefined,
+    summary: `helper apply: ${applied.length} applied (${Array.from(new Set(applied.map((r) => r.type))).join(", ") || "none"}), ${skipped.length} skipped`,
+    ...(skipped.length > 0
+      ? { nextActions: skipped.slice(0, 3).map((s) => `skipped ${s.proposal?.type || "proposal"}: ${s.reason}`) }
+      : {})
+  });
+
   return NextResponse.json({
     ok: true,
     threadId,

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/patch/preflight/route.js

@@ -0,0 +1,152 @@
+/**
+ * POST /api/workspace/patch/preflight
+ *
+ * Dry-run for `PATCH /api/workspace`. Takes the exact body you intend to
+ * PATCH and returns the structured result of every gate the real PATCH will
+ * apply — allowlist + mutation policy (workspace-patch-policy.js) + full
+ * schema validation of the merged config (workspace-schema.js) — without
+ * ever writing.
+ *
+ * Always responds 200; `ok` is the verdict. Agents should preflight any
+ * non-trivial patch (especially dataModel mutations) and fix every reason
+ * before issuing the real PATCH.
+ *
+ * Response:
+ *   {
+ *     ok: boolean,
+ *     allowed: string[],            // the permanent PATCH allowlist
+ *     policy:  { ok, violations: [{ code, path, message }] },
+ *     schema:  { ok, errors: string[] },
+ *     persistence: { mode, canSave, guidance }   // would the write even land?
+ *   }
+ */
+
+import { NextResponse } from "next/server";
+import {
+  applyWorkspaceConfigPatch,
+  describePersistenceMode,
+  readWorkspaceConfig,
+  validateWorkspaceConfig
+} from "@/lib/workspace-config";
+import {
+  WORKSPACE_PATCH_ALLOWED_FIELDS,
+  evaluateWorkspacePatchPolicy,
+  repairPlanForViolations
+} from "@/lib/workspace-patch-policy";
+import { evaluateAppScope, requireAppScope } from "@/lib/workspace-app-registry";
+import { appendOutcomeReceipt } from "@/lib/workspace-outcome-receipts";
+
+async function POST(request) {
+  let patch;
+  try {
+    patch = await request.json();
+  } catch {
+    return NextResponse.json({
+      ok: false,
+      allowed: WORKSPACE_PATCH_ALLOWED_FIELDS,
+      policy: { ok: false, violations: [{ code: "invalid_body", path: "", message: "invalid json body" }] },
+      schema: { ok: false, errors: [] },
+      persistence: null
+    });
+  }
+
+  let currentConfig = null;
+  try {
+    currentConfig = await readWorkspaceConfig();
+  } catch {
+    currentConfig = null;
+  }
+
+  const policy = evaluateWorkspacePatchPolicy(currentConfig, patch);
+
+  // Schema check uses writeWorkspaceConfig's EXACT merge step
+  // (applyWorkspaceConfigPatch) — canvas patches merge over the current
+  // canvas with layout/bindings preservation and null-deletes, never a
+  // top-level replacement — so preflight can never disagree with the real
+  // PATCH about the merged result. Skipped when the body is not a plain
+  // object (policy already reports that).
+  let schema = { ok: true, errors: [] };
+  if (patch && typeof patch === "object" && !Array.isArray(patch)) {
+    const sanitized = {};
+    for (const key of WORKSPACE_PATCH_ALLOWED_FIELDS) {
+      if (Object.prototype.hasOwnProperty.call(patch, key)) sanitized[key] = patch[key];
+    }
+    const merged = applyWorkspaceConfigPatch(currentConfig || {}, sanitized);
+    try {
+      validateWorkspaceConfig({
+        dashboards: merged.dashboards,
+        widgetTypes: merged.widgetTypes,
+        canvas: merged.canvas,
+        dataModel: merged.dataModel
+      });
+    } catch (error) {
+      schema = {
+        ok: false,
+        errors: Array.isArray(error?.details) ? error.details : [error?.message || "invalid workspace config"]
+      };
+    }
+  } else {
+    schema = { ok: false, errors: ["patch must be a plain object"] };
+  }
+
+  // Preflight mirrors PATCH exactly, INCLUDING the app-scope verdict
+  // (OpenClaw: preflight is the single source of truth — if appScopeVerdict
+  // is not allowed, the real PATCH with the same header will 422 the same way).
+  const scope = requireAppScope(request, currentConfig || {});
+  let appScopeVerdict = null;
+  if (scope.scoped) {
+    if (scope.violation) {
+      appScopeVerdict = { allowed: false, appScope: scope.violation.appScope, violations: [scope.violation] };
+    } else {
+      const verdict = evaluateAppScope(currentConfig || {}, patch, scope.appId);
+      appScopeVerdict = { allowed: verdict.ok, appScope: scope.appId, violations: verdict.violations };
+    }
+  }
+
+  const persistence = describePersistenceMode();
+  const ok = policy.ok && schema.ok && (appScopeVerdict ? appScopeVerdict.allowed : true);
+  const repairPlan = repairPlanForViolations(policy.violations);
+  // The single next governed call, when derivable from the verdicts.
+  let safeNextStep;
+  if (ok) {
+    safeNextStep = "PATCH /api/workspace with this exact body";
+  } else if (policy.violations.some((v) => v.code === "live_workflow_field" || v.code === "live_publish_via_patch")) {
+    safeNextStep =
+      "Save the graph as a draft field, prove it with POST /api/workspace/sandbox-run {useDraft:true}, then POST /api/workspace/workflow/publish";
+  } else if (repairPlan.length > 0) {
+    safeNextStep = repairPlan[0];
+  } else if (!schema.ok) {
+    safeNextStep = "Fix the schema errors against apps/workspace/lib/workspace-schema.js, then preflight again";
+  }
+
+  if (!ok) {
+    // Failed attempts are governance signal — visible in the cockpit stream.
+    await appendOutcomeReceipt({
+      kind: "patch-preflight",
+      lane: "untrusted-direct",
+      outcomeStatus: "blocked",
+      changedFields: patch && typeof patch === "object" && !Array.isArray(patch) ? Object.keys(patch) : [],
+      policyVerdict: { ok: policy.ok, violationCodes: policy.violations.map((v) => v.code) },
+      schemaVerdict: { ok: schema.ok, errorCount: schema.errors.length },
+      summary: `preflight blocked: ${[...policy.violations.map((v) => v.code), ...(schema.ok ? [] : ["schema"])].join(", ")}`,
+      nextActions: repairPlan.length ? repairPlan : (safeNextStep ? [safeNextStep] : [])
+    });
+  }
+
+  return NextResponse.json({
+    ok,
+    allowed: WORKSPACE_PATCH_ALLOWED_FIELDS,
+    policy,
+    schema,
+    repairPlan,
+    ...(appScopeVerdict ? { appScopeVerdict } : {}),
+    ...(safeNextStep ? { safeNextStep } : {}),
+    persistence: {
+      mode: persistence.mode,
+      canSave: persistence.canSave,
+      guidance: persistence.guidance
+    }
+  });
+}
+
+export { POST };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/refresh-sources/route.js

@@ -31,6 +31,8 @@
  */
 
 import { NextResponse } from "next/server";
+import { requireAppScope, checkScopedSourceAccess } from "@/lib/workspace-app-registry";
+import { appendOutcomeReceipt } from "@/lib/workspace-outcome-receipts";
 import { readAdapterConfig } from "@/lib/adapters/env";
 import { listGovernedWorkspaceIntegrations } from "@/lib/adapters/integrations";
 import { readWorkspaceConfig, writeWorkspaceSourceRecords } from "@/lib/workspace-config";
@@ -50,6 +52,25 @@ async function POST(request) {
   }
 
   const { sourceIds } = body;
+  // App-scope gate: a scoped agent may only refresh sources referenced on
+  // its registry row (dataSourceIds / derived sourceIds).
+  {
+    let cfgForScope = {};
+    try { cfgForScope = await readWorkspaceConfig(); } catch { cfgForScope = {}; }
+    const scope = requireAppScope(request, cfgForScope);
+    if (scope.scoped) {
+      const violation = scope.violation || checkScopedSourceAccess(scope.context, sourceIds);
+      if (violation) {
+        await appendOutcomeReceipt({
+          kind: "agent-outcome", lane: "untrusted-direct", outcomeStatus: "blocked",
+          appId: violation.appScope || scope.appId,
+          summary: `refresh-sources rejected (422 app scope): ${violation.violationType}`,
+          nextActions: violation.repairPlan
+        });
+        return NextResponse.json(violation, { status: 422 });
+      }
+    }
+  }
   if (!Array.isArray(sourceIds) || sourceIds.length === 0) {
     return NextResponse.json({ error: "sourceIds must be a non-empty array" }, { status: 400 });
   }