@clossys/launcher 0.4.0 → 0.5.0

package/src/plan-bundle.ts

@@ -51,11 +51,11 @@ import { bundleDigest, changeSetDigest } from "./change-set-digest.js";
 import {
   AUTHORIZATION_ABSENT, AUTHORIZATION_PLAN_MISMATCH, BRIEF_PATH, CANONICAL_KEYS, DISCOVERY_ROOTS, EXEMPTION_SURFACES, ID_TOKEN, LEDGER_PATH, derivedPlanItem, SKILLS_MANIFEST_PATH, TEMPLATE_PATHS, canonicalOrder, contentDigest,
   dependencyPointer, discoveryLinkPath, discoveryLinkTarget, isSafeRelativePath, lockfilePath, matchesPathPattern, skillPath, validateApplyBundle, validateRepositoryChangeSet,
-  worstVerdict,
+  worstVerdict, existingDeclarationVersionMatches,
 } from "./change-set-contract.js";
 import type {
   ApplyBundle, ApplyBundleRepository, ApplyCheck, ChangeSetDeferral, ChangeSetItem, ChangeSetPhase, ChangeSetRefusal, DependencyPlacement, DiscoveryRoot,
-  FileChange, KeyChange, LockfileName, PackageInvariant, PackageManagerKind, PinnedPackage, ReleaseAgeSurfaceKind, RepositoryChangeSet, RepositoryProfileObservation,
+  ExistingDeclarationAdoption, FileChange, KeyChange, LockfileName, PackageInvariant, PackageManagerKind, PinnedPackage, ReleaseAgeSurfaceKind, RepositoryChangeSet, RepositoryProfileObservation,
   RepositoryVisibility, TemplateAct,
 } from "./change-set-contract.js";
 import type { InstalledLedger } from "./ledger-contract.js";
@@ -139,6 +139,20 @@ export interface RepositoryObservation {
   readonly npmrcText?: string | null;
 }
 
+/** Derives proof fields from observed source and desired plan acts after explicit scoped consent. */
+export function createExistingDeclarationAdoptions(observation: RepositoryObservation, plan: AdvisorPlan, names: readonly string[], consent: "adopt-existing-declaration"): readonly ExistingDeclarationAdoption[] {
+  const acts = plan.packages ?? [];
+  if (!validateAdvisorPlan(plan).valid || !plan.resolution) throw new TypeError("existing declaration consent needs a resolved desired plan");
+  if (observation.phase !== "setup" || consent !== "adopt-existing-declaration" || names.length === 0 || new Set(names).size !== names.length) throw new TypeError("existing declaration consent is not explicit setup scope");
+  return canonicalOrder(names.map(name => {
+    const act = acts.find(act => act.name === name && act.planItem === `${observation.id}:${name}`);
+    const entries = observation.manifestEntries.filter(entry => entry.name === name);
+    const resolved = observation.lockedPackages.filter(pkg => pkg.name === name);
+    if (!act || !name.startsWith("@clossys/") || entries.length !== 1 || entries[0]?.placement !== act.placement || resolved.length !== 1 || !existingDeclarationVersionMatches(entries[0]!.value,resolved[0]!.version)) throw new TypeError("existing declaration source is not unique and scoped");
+    return {file:"package.json" as const, placement:act.placement, name, beforeVersion:entries[0]!.value, beforeResolved:resolved[0]!, desired:{name:act.name,version:act.version,integrity:act.integrity,planItem:act.planItem,act:act.act,placement:act.placement},observedBaseCommit:observation.baseCommit,desiredSnapshotDigest:plan.resolution!.snapshotDigest,consent};
+  }),row=>[row.name]);
+}
+
 /** A staffed repository no change set is computed for, and why, as an id such as `not-in-inventory`. */
 export interface SkippedRepositoryObservation {
   readonly id: string;
@@ -147,8 +161,12 @@ export interface SkippedRepositoryObservation {
 }
 
 export interface PlanApplyBundleInputs {
+  /** Explicit setup consent, indexed by staffed repository; omitted by default. */
+  readonly existingDeclarationAdoptions?: Readonly<Record<string, readonly ExistingDeclarationAdoption[]>>;
   /** The plan, clossys/advisor/plan.json. It must validate and have `staffing`. */
   readonly plan: AdvisorPlan;
+  /** Explicit authoring agent namespace; omission preserves legacy changes and bytes. */
+  readonly agentProvenance?: "codex" | "claude" | "cursor";
   /** The hub brief, clossys/advisor/brief.json: validated, and without `staffedHere`. Each repository gets its own projection of it. */
   readonly hubBrief: EngagementBrief;
   /** One entry per staffed repository; a staffed repository with no entry is skipped as `not-observed`. */
@@ -317,7 +335,7 @@ interface SetupTemplate {
  * takes the manager, the repository id and the plan's one Starter pin, and
  * nothing else reaches a template.
  */
-function prepareSetup(observation: RepositoryObservation, acts: readonly PlanPackageAct[]): { readonly templates: readonly SetupTemplate[] } | { readonly skip: string } {
+function prepareSetup(observation: RepositoryObservation, acts: readonly PlanPackageAct[], agentProvenance?: "codex" | "claude" | "cursor"): { readonly templates: readonly SetupTemplate[] } | { readonly skip: string } {
   const packageManager = observation.packageManager;
   if (packageManager !== "npm" && packageManager !== "pnpm") return { skip: "package-manager-unsupported" };
   const pins = acts.filter((act) => act.act === "pin-starter");
@@ -335,7 +353,7 @@ function prepareSetup(observation: RepositoryObservation, acts: readonly PlanPac
   }
   const templates: SetupTemplate[] = [];
   for (const { act, id } of TEMPLATE_ITEMS) {
-    const rendered = act === "write-starter-request" ? request : renderSetupTemplate(act, act === "add-caller-workflow" ? { packageManager } : undefined);
+    const rendered = act === "write-starter-request" ? request : renderSetupTemplate(act, act === "add-caller-workflow" ? { packageManager, ...(/^0\.3\./.test(pin.version) ? {existingDeclarationAdoptions:true} : {}) } : act === "add-path-scope-job" && agentProvenance !== undefined ? { agentProvenance } : undefined);
     if (!rendered.ok) throw new TypeError(`the setup template ${act} does not render`);
     templates.push({ id, files: rendered.files });
   }
@@ -362,6 +380,30 @@ function computeChangeSet(
   skillContent: ReadonlyMap<string, string>,
   setupTemplates: readonly SetupTemplate[] | null,
 ): ComputedSet | SkippedSet {
+  const requested = inputs.existingDeclarationAdoptions?.[observation.id];
+  // Retained consent is historical after its first admitted apply.
+  const protectedRows = ledger?.history.at(-1)?.phase === "setup"
+    ? ledger.existingDeclarationAdoptions?.map(({changeSet: _changeSet, ...row}) => row)
+    : undefined;
+  const adoptions = observation.phase === "setup" ? requested : protectedRows;
+  if (observation.phase !== "setup" && requested !== undefined) return {skip: {verdict: "violated", reason: "adoption-consent-not-setup"}};
+  if (adoptions !== undefined) {
+    const starter = acts.find(act => act.act === "pin-starter");
+    if (!starter || !/^0\.3\.[0-9]+$/.test(starter.version)) return {skip: {verdict: "indeterminate", reason: "adoption-starter-unsupported"}};
+    if (!adoptions.length || new Set(adoptions.map(row => row.name)).size !== adoptions.length) return {skip: {verdict: "violated", reason: "adoption-proof-invalid"}};
+    for (const row of adoptions) {
+      const act = acts.find(act => act.planItem === row.desired.planItem);
+      const desired = act && {planItem:act.planItem, act:act.act, name:act.name, version:act.version, integrity:act.integrity, placement:act.placement};
+      const entries = observation.manifestEntries.filter(entry => entry.name === row.name);
+      const consumed = observation.phase === "apply" && row.desired.act === "pin-starter";
+      const prior = consumed ? row.desired : row.beforeResolved;
+      if (row.desiredSnapshotDigest !== inputs.plan.resolution?.snapshotDigest || row.consent !== "adopt-existing-declaration" || row.file !== "package.json" || row.name !== row.desired.name || row.name !== row.beforeResolved.name || row.placement !== row.desired.placement || !row.name.startsWith("@clossys/") ||
+          !existingDeclarationVersionMatches(row.beforeVersion,row.beforeResolved.version) ||
+          (observation.phase === "setup" && row.observedBaseCommit !== observation.baseCommit) ||
+          (!desired || !["planItem","act","name","version","integrity","placement"].every(key => desired[key as keyof typeof desired] === row.desired[key as keyof typeof row.desired])) || entries.length !== 1 || entries[0]?.placement !== row.placement || entries[0]?.value !== (consumed ? row.desired.version : row.beforeVersion) ||
+          !observation.lockedPackages.some(pkg => pkg.name === prior.name && pkg.version === prior.version && pkg.integrity === prior.integrity)) return {skip:{verdict:"violated",reason:"adoption-proof-mismatch"}};
+    }
+  }
   // Paths compare case-insensitively (code rule C3): a base file that differs only in case is the same file on many checkouts.
   // Two (or more) observed files at the same lowercase path -- distinct case variants, or a repeated entry -- have no single
   // base digest between them: the path is occupied by other bytes than any one of them, so it can never be kept, updated or
@@ -519,8 +561,9 @@ function computeChangeSet(
     // when the base happens to already carry the version the plan wants, so it is never waved through as satisfied.
     const row = keyRows.get(pointer);
     const baseAt = entries.find((entry) => entry.placement === act.placement);
-    const own = row === undefined ? (baseAt === undefined ? null : "unowned-existing") : baseAt === undefined ? "deleted" : baseAt.value !== row ? "client-edited" : null;
-    const satisfiedInBase =
+    const adoption = adoptions?.find(proof => proof.name === act.name && proof.desired.act === act.act && !(observation.phase === "apply" && act.act === "pin-starter"));
+    const own = row === undefined ? (baseAt === undefined || adoption !== undefined ? null : "unowned-existing") : baseAt === undefined ? "deleted" : baseAt.value !== row ? "client-edited" : null;
+    const satisfiedInBase = adoption === undefined &&
       entries.length === 1 &&
       baseAt !== undefined &&
       baseAt.value === act.version &&
@@ -543,11 +586,11 @@ function computeChangeSet(
       refused.push({ file: "package.json", pointer, reason: own, item: act.planItem });
       continue;
     }
-    if (row === undefined || act.version !== row) {
+    if (adoption !== undefined || row === undefined || act.version !== row) {
       // The request a setup set wrote names this pin; an apply set that changes it would leave the request naming another, and
       // rewriting the request is not something an apply set does.
       if (act.act === "pin-starter" && observation.phase === "apply") return { skip: { verdict: "indeterminate", reason: "starter-request-stale" } };
-      keys.push({ file: "package.json", pointer, before: row ?? null, after: act.version, item: act.planItem });
+      keys.push({ file: "package.json", pointer, before: adoption?.beforeVersion ?? row ?? null, after: act.version, item: act.planItem });
       invariants.push({ item: act.planItem, ...pinned });
       continue;
     }
@@ -689,6 +732,8 @@ function computeChangeSet(
       schemaVersion: 1,
       kind: "clossys.repository-change-set",
       producer: { name: inputs.producer.name, version: inputs.producer.version },
+      ...(inputs.agentProvenance !== undefined ? { agentProvenance: inputs.agentProvenance } : {}),
+      ...(adoptions !== undefined ? {existingDeclarationAdoptions: adoptions} : {}),
       planDigest: planDigestValue,
       repository: {
         id: observation.id,
@@ -829,10 +874,15 @@ function computeChangeSet(
  * fails its contract.
  */
 export function planApplyBundle(inputs: PlanApplyBundleInputs): PlanApplyBundleResult {
+  if (inputs.agentProvenance !== undefined && !["codex", "claude", "cursor"].includes(inputs.agentProvenance)) throw new TypeError("unsupported agent provenance");
   const planValidation = validateAdvisorPlan(inputs.plan);
   if (!planValidation.valid) throw new TypeError(`the plan does not validate: ${planValidation.reason}`);
   const staffing = inputs.plan.staffing;
   if (staffing === undefined) throw new TypeError("the plan has no staffing, so no repository has a change set");
+  if (inputs.existingDeclarationAdoptions !== undefined) {
+    const mapping = inputs.existingDeclarationAdoptions;
+    if (mapping === null || Array.isArray(mapping) || typeof mapping !== "object" || Reflect.ownKeys(mapping).some(key => typeof key !== "string" || !staffing.some(row => row.repository === key) || !Object.hasOwn(Object.getOwnPropertyDescriptor(mapping,key) ?? {},"value") || !Array.isArray(mapping[key]))) throw new TypeError("existing declaration scope is not a closed staffed mapping");
+  }
   const briefValidation = validateEngagementBrief(inputs.hubBrief);
   if (!briefValidation.valid) throw new TypeError(`the hub brief does not validate: ${briefValidation.reason}`);
   if (inputs.hubBrief.staffedHere !== undefined) throw new TypeError("the hub brief must not have staffedHere; each repository's brief is projected from it");
@@ -894,7 +944,7 @@ export function planApplyBundle(inputs: PlanApplyBundleInputs): PlanApplyBundleR
     let setupTemplates: readonly SetupTemplate[] | null = null;
     if (observation.phase === "setup") {
       // A setup set holds the setup templates (code rule C11); anything that stops them being rendered or the pin being safe is a skip.
-      const prepared = prepareSetup(observation, acts);
+      const prepared = prepareSetup(observation, acts, inputs.agentProvenance);
       if ("skip" in prepared) {
         entries.push({ id: staffingEntry.repository, verdict: "indeterminate", reason: prepared.skip, checks: [] });
         continue;
@@ -920,7 +970,7 @@ export function planApplyBundle(inputs: PlanApplyBundleInputs): PlanApplyBundleR
     const { changeSet, checks } = result;
     const digest = changeSetDigest(changeSet);
     const short = digest.slice("sha256:".length, "sha256:".length + 12);
-    const set = { ...changeSet, branch: `clossys/apply-${short}`, pullRequest: { title: `Clossys: apply plan ${short}` }, changeSetDigest: digest };
+    const set = { ...changeSet, branch: `${changeSet.agentProvenance ?? "clossys"}/apply-${short}`, pullRequest: { title: `Clossys: apply plan ${short}` }, changeSetDigest: digest };
     entries.push({ pending: computed.length });
     computed.push({ id: staffingEntry.repository, staffingIndex, phase: observation.phase, set, checks });
   }

package/src/plan-command.ts

@@ -37,7 +37,16 @@ import type { PlanApplyBundleResult, RepositoryObservation, SkippedRepositoryObs
 import { validateAdvisorPlan, validateEngagementBrief } from "./plan-contract.js";
 import type { AdvisorPlan, EngagementBrief } from "./plan-contract.js";
 
-export const PLAN_USAGE = `Usage: launcher-apply-plan plan [--help]
+export const PLAN_USAGE = `Usage: launcher-apply-plan plan [--agent codex|claude|cursor] [--adopt-existing <consent.json>] [--help]
+
+--agent selects the authoring agent namespace for generated apply branches.
+The choice is covered by the change-set and approval digests. Omitting it
+preserves legacy clossys/apply branches and stored change sets. Use the same
+choice when recomputing an approved bundle.
+
+--adopt-existing reads an explicit repository-to-proof-row mapping for setup.
+It supplies scope, not approval, and requires Starter 0.3.x. Omit it for apply;
+the protected setup ledger supplies the frozen scope automatically.
 
 Run in the hub. Computes the apply bundle for the plan file in the working
 tree, reports whether that file is the one committed at HEAD, and prints the
@@ -436,7 +445,19 @@ export async function planMain(argv: readonly string[], options: PlanCommandOpti
       stdout(`${PLAN_USAGE}\n`);
       return 0;
     }
-    if (argv.length !== 0) return refuse("usage");
+    let agentProvenance: "codex" | "claude" | "cursor" | undefined;
+    let adoptionPath: string | undefined;
+    for (let index=0; index<argv.length; index+=2) {
+      const flag=argv[index]; const value=argv[index+1];
+      if (flag === "--agent" && agentProvenance === undefined && value !== undefined && ["codex","claude","cursor"].includes(value)) agentProvenance=value as "codex"|"claude"|"cursor";
+      else if (flag === "--adopt-existing" && adoptionPath === undefined && value !== undefined) adoptionPath=value;
+      else return refuse("usage");
+    }
+    let existingDeclarationAdoptions: import("./plan-bundle.js").PlanApplyBundleInputs["existingDeclarationAdoptions"];
+    if (adoptionPath !== undefined) {
+      try { existingDeclarationAdoptions=readContractDocument(readFileSync(adoptionPath)) as NonNullable<typeof existingDeclarationAdoptions>; }
+      catch { return refuse("usage"); }
+    }
     let hub: string;
     try {
       hub = realpathSync(options.cwd ?? process.cwd());
@@ -475,6 +496,8 @@ export async function planMain(argv: readonly string[], options: PlanCommandOpti
         authorization,
         computedAt,
         heldChangeSets,
+        ...(agentProvenance !== undefined ? { agentProvenance } : {}),
+        ...(existingDeclarationAdoptions !== undefined ? {existingDeclarationAdoptions} : {}),
       });
     } catch {
       return refuse("planner-refused");

package/src/setup-template-scripts.ts

@@ -1,7 +1,9 @@
 /**
  * Pure renderers for the setup template acts' script and workflow files.
  *
- * Each renderer takes no input and returns the exact bytes of one file, so
+ * Each renderer returns exact file bytes; path scope optionally takes the
+ * supported authoring agent provenance. With no input it preserves legacy
+ * bytes. Rendering is pure, so
  * the text is a pure function of this module alone: no clock, no randomness,
  * no filesystem, no environment. Everything that reads a clock or a
  * repository does so inside the emitted script, when a workflow runs it, and
@@ -505,8 +507,14 @@ try {
  * The standalone path-scope script (its text ends in one LF). The
  * path-scope workflow embeds it; a test runs it with `node` directly.
  */
-export function renderPathScopeScript(): string {
-  return PATH_SCOPE_SCRIPT;
+export function renderPathScopeScript(agentProvenance: "codex" | "claude" | "cursor" | undefined = undefined): string {
+  if (agentProvenance === undefined) return PATH_SCOPE_SCRIPT;
+  if (!["codex", "claude", "cursor"].includes(agentProvenance)) throw new TypeError("unsupported agent provenance");
+  // Keep legacy bytes unchanged. Explicit provenance opts into the expanded
+  // branch recognizer; every supported namespace still runs the full checks.
+  return PATH_SCOPE_SCRIPT
+    .replace('const APPLY_PREFIX = "clossys/apply-";', 'const APPLY_PREFIX = "a supported apply branch";\nconst APPLY_BRANCH = /^(clossys|codex|claude|cursor)\\/apply-[0-9a-f]{12}$/;')
+    .replace('if (!headRef.startsWith(APPLY_PREFIX)) {', 'if (!APPLY_BRANCH.test(headRef)) {\n    if (headRef.includes("/apply")) refuse("unsupported or malformed apply branch");');
 }
 
 const PATH_SCOPE_WORKFLOW_HEAD = [
@@ -563,9 +571,10 @@ const PATH_SCOPE_WORKFLOW_HEAD = [
 const RUN_BODY_INDENT = "          ";
 
 /** The bytes of `.github/workflows/clossys-path-scope.yml`: the script embedded in a quoted heredoc. */
-export function renderPathScopeWorkflow(): string {
-  const body = PATH_SCOPE_SCRIPT.slice(0, -1)
+export function renderPathScopeWorkflow(agentProvenance: "codex" | "claude" | "cursor" | undefined = undefined): string {
+  const body = renderPathScopeScript(agentProvenance).slice(0, -1)
     .split("\n")
     .map((line) => (line === "" ? "" : `${RUN_BODY_INDENT}${line}`));
-  return [...PATH_SCOPE_WORKFLOW_HEAD, ...body, `${RUN_BODY_INDENT}${HEREDOC_TERMINATOR}`, ""].join("\n");
+  const head = agentProvenance === undefined ? PATH_SCOPE_WORKFLOW_HEAD : PATH_SCOPE_WORKFLOW_HEAD.map((line) => line.replace("head branch starts with clossys/apply-.", "head branch is a legacy or supported agent apply branch."));
+  return [...head, ...body, `${RUN_BODY_INDENT}${HEREDOC_TERMINATOR}`, ""].join("\n");
 }

package/src/setup-templates.ts

@@ -49,10 +49,10 @@ export type TemplateResult =
 
 /**
  * The Starter versions a setup may pin, for documentation. The check below is
- * the rule: an exact `0.2.PATCH`, with no range, prerelease, build metadata, or
+ * the rule: an exact `0.2.PATCH` or `0.3.PATCH`, with no range, prerelease, build metadata, or
  * leading zero.
  */
-export const STARTER_PIN_RANGE = ">=0.2.0 <0.3.0";
+export const STARTER_PIN_RANGE = ">=0.2.0 <0.4.0";
 
 const REQUEST_PATH = ".starter/request.json";
 const DECISION_WORKFLOW_PATH = ".github/workflows/clossys-adoption-decision.yml";
@@ -61,7 +61,7 @@ const STARTER_NAME = "@clossys/starter";
 const STARTER_BIN = "foundry-starter";
 const SNAPSHOT_MAX_AGE_MS = 3_600_000;
 
-const STARTER_VERSION = /^0\.2\.(?:0|[1-9][0-9]{0,8})$/u;
+const STARTER_VERSION = /^0\.[23]\.(?:0|[1-9][0-9]{0,8})$/u;
 
 /**
  * Whether `version` is a Starter version the templates support: exactly the
@@ -305,9 +305,10 @@ const LAST_STEPS: readonly string[] = [
   "",
 ];
 
-function decisionWorkflow(manager: SetupPackageManager): string {
+function decisionWorkflow(manager: SetupPackageManager, adoptionProofs = false): string {
   const install = manager === "npm" ? NPM_INSTALL : PNPM_INSTALL;
-  return [...workflowTop(manager), ...FIRST_STEPS, ...install, ...LAST_STEPS].join("\n");
+  const bytes = [...workflowTop(manager), ...FIRST_STEPS, ...install, ...LAST_STEPS].join("\n");
+  return adoptionProofs ? bytes.replace("            /clossys/.state/installed.json", "            /clossys/.state/installed.json\n            /package.json\n            /" + (manager === "npm" ? "package-lock.json" : "pnpm-lock.yaml")) : bytes;
 }
 
 /** Render `.github/workflows/clossys-adoption-decision.yml` for npm or pnpm, or refuse at `packageManager`. */
@@ -416,7 +417,7 @@ export function renderProductCiWorkflow(): string {
 // The dispatcher
 // ---------------------------------------------------------------------------
 
-const CALLER_KEYS: ReadonlySet<string> = new Set(["packageManager"]);
+const CALLER_KEYS: ReadonlySet<string> = new Set(["packageManager", "existingDeclarationAdoptions"]);
 
 function isTemplateAct(value: unknown): value is TemplateAct {
   return typeof value === "string" && Object.prototype.hasOwnProperty.call(TEMPLATE_PATHS, value);
@@ -431,9 +432,10 @@ function checked(act: TemplateAct, result: TemplateResult): TemplateResult {
 }
 
 function renderCallerWorkflows(input: unknown): TemplateResult {
-  if (!isPlainRecord(input, CALLER_KEYS) || Reflect.ownKeys(input).length !== 1) return refuse("input-invalid", "input");
-  const decision = renderAdoptionDecisionWorkflow(ownValue(input, "packageManager"));
-  if (!decision.ok) return decision;
+  if (!isPlainRecord(input, CALLER_KEYS) || (Reflect.ownKeys(input).length !== 1 && (Reflect.ownKeys(input).length !== 2 || ownValue(input,"existingDeclarationAdoptions") !== true))) return refuse("input-invalid", "input");
+  const manager = ownValue(input,"packageManager");
+  if (!isPackageManager(manager)) return refuse("package-manager-unsupported", "packageManager");
+  const decision = {ok:true as const, files:[{path:DECISION_WORKFLOW_PATH, bytes:decisionWorkflow(manager,ownValue(input,"existingDeclarationAdoptions") === true)}]};
   return {
     ok: true,
     files: [
@@ -452,7 +454,8 @@ function renderFixedFile(input: unknown, path: string, bytes: () => string): Tem
 /**
  * Render the files one setup act writes, or refuse. `add-caller-workflow` takes
  * `{ packageManager }`, `write-starter-request` takes a `StarterRequestInput`,
- * and `add-ci-template` and `add-path-scope-job` take no input. The returned
+ * `add-ci-template` takes no input, and `add-path-scope-job` optionally takes
+ * `{ agentProvenance }`. The returned
  * paths are always `TEMPLATE_PATHS[act]`, in that order.
  */
 export function renderSetupTemplate(act: TemplateAct, input?: unknown): TemplateResult {
@@ -465,7 +468,12 @@ export function renderSetupTemplate(act: TemplateAct, input?: unknown): Template
       return checked(name, renderStarterRequest(input));
     case "add-ci-template":
       return checked(name, renderFixedFile(input, CI_WORKFLOW_PATH, renderProductCiWorkflow));
-    case "add-path-scope-job":
-      return checked(name, renderFixedFile(input, PATH_SCOPE_WORKFLOW_PATH, renderPathScopeWorkflow));
+    case "add-path-scope-job": {
+      if (input === undefined) return checked(name, renderFixedFile(input, PATH_SCOPE_WORKFLOW_PATH, renderPathScopeWorkflow));
+      if (!isPlainRecord(input, new Set(["agentProvenance"])) || Reflect.ownKeys(input).length !== 1) return refuse("input-invalid", "input");
+      const agent = ownValue(input, "agentProvenance");
+      if (agent !== "codex" && agent !== "claude" && agent !== "cursor") return refuse("input-invalid", "input");
+      return checked(name, { ok: true, files: [{ path: PATH_SCOPE_WORKFLOW_PATH, bytes: renderPathScopeWorkflow(agent) }] });
+    }
   }
 }