@sublang/playbook 17.4.1 → 17.5.0

package/docs/cli.md

@@ -181,6 +181,7 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 | Flag | Meaning |
 | --- | --- |
 | `--with <path>` | overlay current config for a fresh session or compatible ordinary reopen; repeatable |
+| `--module <id>=<specifier>` | supply playbook `<id>`'s registry module ahead of its `playbooks.<id>.from`; repeatable, one per id; a relative path resolves against the current directory |
 | `--no-provision` | do not create missing engine links for configured filesystem registries |
 | `--json` | print exactly one `sessionId` / `reply` object |
 | `--verbose` | add Captain telemetry topic names to stderr |
@@ -243,6 +244,26 @@ A directory where both imports already resolve is untouched, and
 module's directory is a git repository, add `node_modules/` to its
 `.gitignore` so provisioned links never enter player commits.
 
+A launch can also supply a playbook's module, which is never written back to
+your config files, for example when an embedding host keeps each playbook
+installed in an environment of its own. `--module <id>=<specifier>` (or
+`--module=<id>=<specifier>`) is accepted by `playbook`, `playbook --session`,
+`--list`, `--theme-diagnostics`, and fresh or continuing `playbook run`, and
+wins over that playbook's `from` the way a `--with` fragment wins over the
+file. An absolute path becomes a file URL, a relative path resolves against
+the directory where you run the command, and a file URL or package specifier
+is kept. The flag is never forwarded to tmux-play or sent as Boss input; it is
+refused beside a raw `--config`, during uncertain-turn recovery, for an id
+given twice, and for an id the config does not enable
+([[playbook-cli-94](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-94)],
+[[playbook-cli-96](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-96)],
+[DR-083](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/083-module-locations-supplied-at-launch.md)).
+
+```sh
+playbook --module code=/opt/env/code/registry.mjs
+playbook run --module review=@sublang/playbook/review/registry "/review the last commit"
+```
+
 ### Continuing a Captain session
 
 Interactive and headless commands write the same logical-session records in
@@ -279,9 +300,15 @@ competing front end fails closed instead of forking the history.
 
 An ordinary reopen reads current config and any opening `--with` fragments,
 projects them to the stored catalog and player roster, and requires the stored
-role bindings plus every structural setting to remain exact. Compatible
-current `model`, `effort`, and optional `fastMode`, `subagentModel`, and
-`subagentEffort` settings apply to the next call. Boolean `false` explicitly
+role bindings plus every structural setting to remain exact. A playbook whose
+current config names no `from` and receives no `--module` keeps the module the
+session records. Otherwise the module so taken — the supplied one, else a
+present `from` — must equal the stored module; a present `from` beside a
+supplied module is checked for form only. A `--module` for a playbook your
+config enables but the session does not hold is ignored, while one naming no
+playbook of your config is refused. Compatible current `model`, `effort`, and
+optional `fastMode`, `subagentModel`, and `subagentEffort` settings apply to
+the next call. Boolean `false` explicitly
 resets model, effort, subagent model, or subagent effort to the provider
 default, but `fastMode: false` is a literal
 disabled request; omission selects the provider default or inherits the player

package/docs/configuration.md

@@ -57,8 +57,11 @@ preflight their auth.
 
 Within a `playbooks.<id>` block, `from` (the registry module), `command` (an
 optional slash-command override), and `roles` are launcher-owned; every other
-key is that playbook's option slice. Every manifest role must be present
-exactly once. The launcher injects the rest — you do not write host wiring by
+key is that playbook's option slice. `from` is required unless the launch
+supplies that playbook's module with `--module <id>=<specifier>` (or an
+embedding host's `modules` option), or a reopened session already records
+one; see [Modules supplied at launch](#modules-supplied-at-launch). Every
+manifest role must be present exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
 The launcher seeds one adapter for the Captain and all stable players from
@@ -422,6 +425,33 @@ Before either front end imports a filesystem registry, the shared launcher
 checks and, unless `--no-provision` is set, provisions its runtime engine
 links as described in [Using the CLI](cli.md#external-playbooks-and-engine-provisioning).
 
+### Modules supplied at launch
+
+A config may leave `playbooks.<id>.from` out when the launch supplies the
+module instead, so the shared file names no machine-specific path:
+
+```yaml
+playbooks:
+  my-workflow:
+    roles:
+      worker: my.worker
+```
+
+```sh
+playbook run --module my-workflow=/opt/env/my-workflow.js "/my-workflow perform the task"
+```
+
+A supplied module wins over a `from` the file does carry, and it is never
+written back to your config files. A playbook with neither is refused before any import:
+`playbooks.<id> names no module: set playbooks.<id>.from or supply a module for
+<id> (--module <id>=<specifier>)`. A malformed `from` is still refused even
+when a module is supplied. Reopening a recorded session needs neither: with
+no `from` and no `--module`, it uses the module the session already records.
+Otherwise the module so taken — the supplied one, else a present `from` — must
+equal the stored module; a present `from` beside a supplied module is checked
+for form only
+([DR-083](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/083-module-locations-supplied-at-launch.md)).
+
 ## Migrating per-playbook players
 
 The former `playbooks.<id>.players` shape made agent configuration and local

package/docs/embedding.md

@@ -402,6 +402,35 @@ The controller owns uncertainty, reconciliation, settlement and lease release;
 observers receive presentation events or exact appended envelopes through
 `onStoredRecord`. Keep the controller open for successive turns.
 
+`loadLaunchPlan()` and `normalizeLaunchPlan()` accept an optional `modules`
+option, a read-only record from playbook id to module specifier. A host that
+keeps each playbook installed somewhere of its own hands the module locations
+there instead of writing them into the shared config, whose
+`playbooks.<id>.from` may then be left out:
+
+```ts
+import { loadLaunchPlan } from '@sublang/playbook/session-host';
+
+const plan = await loadLaunchPlan({
+  userConfigPath,
+  modules: { code: '/opt/env/code/registry.mjs', review: '@sublang/playbook/review/registry' },
+});
+```
+
+Each enabled playbook takes `modules[id]` ahead of its `from`. An absolute
+path becomes a file URL, while a file URL or package specifier is kept; a
+relative path is refused, so resolve it against your own working directory
+first. On a new launch, a module naming no enabled playbook is refused before
+any import; with `selectedMembers`, one for a current playbook outside the
+selection is skipped, while one naming no current playbook is still refused.
+These loaders hold no stored session record, so they refuse a playbook with
+neither a supplied module nor `from`, with or without `selectedMembers`; only
+the CLI's reopen of a recorded session falls back to the module that record
+holds. The preparation hook, single import, registry checks and the plan's
+canonical `from` are unchanged, and a supplied module is never written back to
+your config files
+([DR-083](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/083-module-locations-supplied-at-launch.md)).
+
 `shared.readLeaseState(sessionId)` reports `active`, `idle` or `unknown` without
 changing files. Use it for presentation; mutations still require a lease.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.4.1",
+  "version": "17.5.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -84,6 +84,73 @@ export function extractWithFlags(argv) {
   return { withPaths, rest };
 }
 
+// PBCLI-94 (DR-083): one `--module` value names `<id>=<specifier>`, split at
+// its first `=` so a specifier may itself carry one.
+export function parseModuleFlagValue(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error("--module needs an <id>=<specifier> value");
+  }
+  const separator = value.indexOf("=");
+  if (separator < 0) {
+    throw new Error(
+      `--module ${JSON.stringify(value)} must be <id>=<specifier>`,
+    );
+  }
+  const id = value.slice(0, separator);
+  const specifier = value.slice(separator + 1);
+  if (id.length === 0) {
+    throw new Error(`--module ${JSON.stringify(value)} names no playbook id`);
+  }
+  if (specifier.length === 0) {
+    throw new Error(
+      `--module ${JSON.stringify(value)} names no module specifier`,
+    );
+  }
+  return [id, specifier];
+}
+
+// PBCLI-94 (DR-083): split ordered `--module <id>=<specifier>` pairs out of an
+// argument vector, beside `--with`. The caller's vector is never changed.
+export function extractModuleFlags(argv) {
+  const modulePairs = [];
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--module") {
+      modulePairs.push(parseModuleFlagValue(argv[i + 1]));
+      i += 1;
+    } else if (arg.startsWith("--module=")) {
+      modulePairs.push(parseModuleFlagValue(arg.slice("--module=".length)));
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { modulePairs, rest };
+}
+
+// PBCLI-94 (DR-083): the CLI's supplied modules, one per playbook id. A
+// relative filesystem path resolves against the invocation's working
+// directory here, because the loader refuses relative paths.
+export function suppliedModulesFromFlags(modulePairs, cwd = process.cwd()) {
+  const seen = new Set();
+  const entries = [];
+  for (const [id, specifier] of modulePairs) {
+    if (seen.has(id)) {
+      throw new Error(
+        `--module names playbook ${JSON.stringify(id)} more than once`,
+      );
+    }
+    seen.add(id);
+    entries.push([
+      id,
+      isRelativeFilesystemRegistrySpecifier(specifier)
+        ? resolve(cwd, specifier)
+        : specifier,
+    ]);
+  }
+  return Object.freeze(Object.fromEntries(entries));
+}
+
 // PBCLI-25: an overlay fragment is a top-level-format YAML map.
 export function loadOverlayFragment(overlayPath) {
   const resolved = resolve(overlayPath);
@@ -244,6 +311,76 @@ export function canonicalizeRegistrySpecifier(from, configPath) {
   return from;
 }
 
+// PBCLI-94 (DR-083): validate the loader's `modules` option — a read-only
+// record from playbook id to module specifier — and canonicalize each value by
+// the configured-module rules, except that a relative path has no config
+// directory to anchor it and is refused. Every id must name a playbook of the
+// current config; an ordinary reopen skips one the stored catalog lacks.
+function resolveSuppliedModules(modules, enabledIds, currentIds) {
+  const supplied = new Map();
+  if (modules === undefined) return supplied;
+  const record = cloneJson(modules, "modules");
+  if (!isPlainObject(record)) {
+    throw new Error(
+      "modules must be a record from playbook id to module specifier",
+    );
+  }
+  for (const [id, specifier] of Object.entries(record)) {
+    if (!currentIds.has(id)) {
+      throw new Error(
+        `a module was supplied for ${JSON.stringify(id)}, which names no enabled playbook`,
+      );
+    }
+    if (
+      typeof specifier !== "string" ||
+      specifier.trim().length === 0 ||
+      specifier !== specifier.trim()
+    ) {
+      throw new Error(
+        `the module supplied for ${id} must be a canonical trimmed module specifier`,
+      );
+    }
+    if (isRelativeFilesystemRegistrySpecifier(specifier)) {
+      throw new Error(
+        `the module supplied for ${id} is a relative path; supply an absolute path, a file URL, or a package specifier`,
+      );
+    }
+    // A current playbook outside the stored catalog is ignored on a reopen,
+    // once its value has passed the checks above.
+    if (!enabledIds.includes(id)) continue;
+    supplied.set(
+      id,
+      !specifier.startsWith("file:") && isAbsolute(specifier)
+        ? pathToFileURL(specifier).href
+        : specifier,
+    );
+  }
+  return supplied;
+}
+
+// PBCLI-94 (DR-083): add the ids a layer's own `playbooks` map holds, read as
+// keys only, so a reopen can name a stray supplied id without inspecting any
+// member outside its stored selection.
+function addCurrentPlaybookIds(layer, ids = new Set()) {
+  if (!isPlainObject(layer)) return ids;
+  const descriptor = Object.getOwnPropertyDescriptor(layer, "playbooks");
+  if (
+    descriptor === undefined ||
+    !hasOwn(descriptor, "value") ||
+    !isPlainObject(descriptor.value)
+  ) {
+    return ids;
+  }
+  for (const id of Object.keys(descriptor.value)) ids.add(id);
+  return ids;
+}
+
+function missingModuleError(id) {
+  return new Error(
+    `playbooks.${id} names no module: set playbooks.${id}.from or supply a module for ${id} (--module ${id}=<specifier>)`,
+  );
+}
+
 function isRelativeFilesystemRegistrySpecifier(from) {
   return (
     from.startsWith("./") ||
@@ -264,6 +401,7 @@ export async function loadLaunchPlan({
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
   selectedMembers,
+  modules,
   env = process.env,
   homeDir = env.HOME ?? homedir(),
 }) {
@@ -280,19 +418,26 @@ export async function loadLaunchPlan({
       `the top-level config at ${userConfigPath} must be a YAML map before --with can overlay it`,
     );
   }
+  const currentPlaybookIds = addCurrentPlaybookIds(top);
   for (const overlayPath of overlayPaths) {
     const overlay = loadOverlayFragment(overlayPath);
+    addCurrentPlaybookIds(overlay, currentPlaybookIds);
     top =
       selectedMembers === undefined
         ? mergeConfigs(top, overlay)
         : mergeSelectedConfigs(top, overlay, selectedMembers);
   }
-  return await normalizeLaunchPlan(top, {
-    loadModule,
-    configPath: userConfigPath,
-    prepareRegistryModule,
-    selectedMembers,
-  });
+  return await normalizeLaunchPlanWith(
+    top,
+    {
+      loadModule,
+      configPath: userConfigPath,
+      prepareRegistryModule,
+      selectedMembers,
+      modules,
+    },
+    currentPlaybookIds,
+  );
 }
 
 // PBCLI-22/49: an interactive selected launch may project current tuning and
@@ -304,6 +449,7 @@ export async function loadSelectedLaunchPlanDataOnly({
   userConfigPath,
   overlayPaths = [],
   structuralProjection,
+  modules,
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
   env = process.env,
@@ -319,28 +465,38 @@ export async function loadSelectedLaunchPlanDataOnly({
       `the top-level config at ${userConfigPath} must be a YAML map before --with can overlay it`,
     );
   }
+  const currentPlaybookIds = addCurrentPlaybookIds(top);
   top = projectSelectedLayer(
     top,
     validateSelectedMembers(selectedMembers),
     "config",
   );
   for (const overlayPath of overlayPaths) {
-    top = mergeSelectedConfigs(
-      top,
-      loadOverlayFragment(overlayPath),
-      selectedMembers,
-    );
+    const overlay = loadOverlayFragment(overlayPath);
+    addCurrentPlaybookIds(overlay, currentPlaybookIds);
+    top = mergeSelectedConfigs(top, overlay, selectedMembers);
   }
-  return await normalizeSelectedLaunchPlanDataOnly(top, {
-    configPath: userConfigPath,
-    stored,
-    selectedMembers,
-  });
+  return await normalizeSelectedLaunchPlanDataOnlyWith(
+    top,
+    { configPath: userConfigPath, stored, selectedMembers, modules },
+    currentPlaybookIds,
+  );
 }
 
-export async function normalizeSelectedLaunchPlanDataOnly(
+export async function normalizeSelectedLaunchPlanDataOnly(top, options = {}) {
+  return await normalizeSelectedLaunchPlanDataOnlyWith(
+    top,
+    options,
+    addCurrentPlaybookIds(top),
+  );
+}
+
+// `currentPlaybookIds` names every playbook of the current merged config,
+// gathered before the layers were projected to the stored selection.
+async function normalizeSelectedLaunchPlanDataOnlyWith(
   top,
-  { configPath, stored, selectedMembers } = {},
+  { configPath, stored, selectedMembers, modules } = {},
+  currentPlaybookIds,
 ) {
   stored = validateStoredStructuralProjection(stored);
   const expectedMembers = selectedMembersFromStoredStructure(stored);
@@ -390,6 +546,11 @@ export async function normalizeSelectedLaunchPlanDataOnly(
   );
 
   const playbooksCfg = requireObject(top.playbooks, "playbooks");
+  const suppliedModules = resolveSuppliedModules(
+    modules,
+    expectedMembers.playbookIds,
+    currentPlaybookIds,
+  );
   const tuningChecks = [];
   let tuningCheckIndex = 0;
   const authored = new Map();
@@ -400,20 +561,30 @@ export async function normalizeSelectedLaunchPlanDataOnly(
       throw legacyPlayersError(`playbooks.${id}.players`, configPath);
     }
     rejectConfiguredHostCapabilities(block, `playbooks.${id}`);
+    const hasFrom = hasOwn(block, "from");
     if (
-      typeof block.from !== "string" ||
-      block.from.trim().length === 0 ||
-      block.from !== block.from.trim()
+      hasFrom &&
+      (typeof block.from !== "string" ||
+        block.from.trim().length === 0 ||
+        block.from !== block.from.trim())
     ) {
       throw new Error(
         `playbooks.${id}.from must be a canonical trimmed module specifier`,
       );
     }
-    const configuredFrom = canonicalizeRegistrySpecifier(
-      block.from,
-      configPath,
-    );
-    if (configuredFrom !== storedItem.from) {
+    // PBCLI-22/94 (DR-083): a supplied module wins over `from`; with neither,
+    // the reopen takes the module the session already records.
+    const suppliedModule = suppliedModules.get(id);
+    if (suppliedModule !== undefined) {
+      if (suppliedModule !== storedItem.from) {
+        throw new Error(
+          `the module supplied for ${id} differs from the stored structural projection`,
+        );
+      }
+    } else if (
+      hasFrom &&
+      canonicalizeRegistrySpecifier(block.from, configPath) !== storedItem.from
+    ) {
       throw new Error(
         `playbooks.${id}.from changed from the stored structural projection`,
       );
@@ -663,9 +834,26 @@ function rejectConfiguredHostCapabilities(value, path) {
 // PBCLI-46: normalize into a detached, deeply frozen JSON plan. The plan has
 // only execution data and presentation data; imported registry functions are
 // consulted for validation and then discarded.
-export async function normalizeLaunchPlan(
+export async function normalizeLaunchPlan(top, options = {}) {
+  return await normalizeLaunchPlanWith(
+    top,
+    options,
+    addCurrentPlaybookIds(top),
+  );
+}
+
+// `currentPlaybookIds` names every playbook of the current merged config,
+// gathered before a reopen projected the layers to its selection.
+async function normalizeLaunchPlanWith(
   top,
-  { loadModule, configPath, prepareRegistryModule, selectedMembers } = {},
+  {
+    loadModule,
+    configPath,
+    prepareRegistryModule,
+    selectedMembers,
+    modules,
+  } = {},
+  currentPlaybookIds,
 ) {
   const importModule = loadModule ?? ((specifier) => import(specifier));
   top = projectSelectedMembers(top, selectedMembers);
@@ -714,6 +902,13 @@ export async function normalizeLaunchPlan(
   if (ids.some((id) => id.trim().length === 0 || id !== id.trim())) {
     throw new Error("playbooks keys must be canonical trimmed nonblank ids");
   }
+  // PBCLI-94 (DR-083): supplied modules are checked before any preparation
+  // or import; an ordinary reopen skips a current playbook it does not hold.
+  const suppliedModules = resolveSuppliedModules(
+    modules,
+    ids,
+    selectedMembers === undefined ? new Set(ids) : currentPlaybookIds,
+  );
 
   let captain = resolveDelegationDefault(
     resolveAgent(top.captain, "captain", ["from", "options"]),
@@ -741,16 +936,28 @@ export async function normalizeLaunchPlan(
       throw legacyPlayersError(`playbooks.${id}.players`, configPath);
     }
     rejectConfiguredHostCapabilities(block, `playbooks.${id}`);
-    const from = block.from;
+    const hasFrom = hasOwn(block, "from");
     if (
-      typeof from !== "string" ||
-      from.trim().length === 0 ||
-      from !== from.trim()
+      hasFrom &&
+      (typeof block.from !== "string" ||
+        block.from.trim().length === 0 ||
+        block.from !== block.from.trim())
     ) {
       throw new Error(
         `playbooks.${id}.from must be a canonical trimmed module specifier`,
       );
     }
+    // PBCLI-9/94 (DR-083): the supplied module wins over `from`, as a --with
+    // fragment wins over the file; with neither, the playbook names no module.
+    const suppliedModule = suppliedModules.get(id);
+    if (!hasFrom && suppliedModule === undefined) {
+      throw missingModuleError(id);
+    }
+    const from = suppliedModule ?? block.from;
+    const fromLabel =
+      suppliedModule === undefined
+        ? `playbooks.${id}.from`
+        : `the module supplied for ${id}`;
     if (
       block.command !== undefined &&
       (typeof block.command !== "string" ||
@@ -816,10 +1023,12 @@ export async function normalizeLaunchPlan(
         ([key]) => !PLAYBOOK_LAUNCHER_KEYS.includes(key),
       ),
     );
-    const configuredFrom = canonicalizeRegistrySpecifier(from, configPath);
+    const configuredFrom =
+      suppliedModule ?? canonicalizeRegistrySpecifier(from, configPath);
     configuredPlaybooks.push({
       id,
       from,
+      fromLabel,
       configuredFrom,
       commandOverride: block.command,
       roles,
@@ -906,7 +1115,7 @@ export async function normalizeLaunchPlan(
   // registry modules evaluated and others untouched.
   const preparedPlaybooks = [];
   for (const configured of configuredPlaybooks) {
-    const { id, from, configuredFrom } = configured;
+    const { id, from, fromLabel, configuredFrom } = configured;
     let preparedFrom = configuredFrom;
     if (prepareRegistryModule !== undefined) {
       try {
@@ -919,7 +1128,7 @@ export async function normalizeLaunchPlan(
         if (prepared !== undefined) preparedFrom = prepared;
       } catch (cause) {
         throw new Error(
-          `playbooks.${id}.from "${from}" failed to prepare: ${errorMessage(cause)}`,
+          `${fromLabel} "${from}" failed to prepare: ${errorMessage(cause)}`,
         );
       }
       if (
@@ -927,13 +1136,13 @@ export async function normalizeLaunchPlan(
         preparedFrom.trim().length === 0
       ) {
         throw new Error(
-          `playbooks.${id}.from "${from}" preparation must return a module specifier`,
+          `${fromLabel} "${from}" preparation must return a module specifier`,
         );
       }
     }
     preparedFrom = canonicalizePreparedRegistrySpecifier(
       preparedFrom,
-      `playbooks.${id}.from`,
+      fromLabel,
     );
     preparedPlaybooks.push({ ...configured, preparedFrom });
   }
@@ -945,6 +1154,7 @@ export async function normalizeLaunchPlan(
   for (const {
     id,
     from,
+    fromLabel,
     preparedFrom,
     commandOverride,
     roles,
@@ -956,14 +1166,14 @@ export async function normalizeLaunchPlan(
       mod = await importModule(preparedFrom);
     } catch (cause) {
       throw new Error(
-        `playbooks.${id}.from "${from}" failed to import: ${errorMessage(cause)}`,
+        `${fromLabel} "${from}" failed to import: ${errorMessage(cause)}`,
       );
     }
     const entry = snapshotRegistryEntry(mod?.default);
     const registryProblem = invalidRegistryEntryReason(entry);
     if (registryProblem !== undefined) {
       throw new Error(
-        `playbooks.${id}.from "${from}" exposes no valid registry entry: ` +
+        `${fromLabel} "${from}" exposes no valid registry entry: ` +
           registryProblem,
       );
     }

package/reference/sdlc/code.playbook/bin/playbook.js

@@ -18,10 +18,12 @@ import {
 } from "./adapter-sdk.js";
 import {
   adaptersFromLaunchPlan,
+  extractModuleFlags,
   extractWithFlags,
   loadLaunchPlan,
   loadSelectedLaunchPlanDataOnly,
   projectTmuxConfig,
+  suppliedModulesFromFlags,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
   resolveFormerUserConfigPaths,
@@ -54,15 +56,18 @@ export {
   checkReadiness,
   composeGenericConfig,
   deriveLaunchReadiness,
+  extractModuleFlags,
   extractWithFlags,
   loadLaunchPlan,
   loadOverlayFragment,
   mergeConfigs,
   migrateRetiredProfiles,
   normalizeLaunchPlan,
+  parseModuleFlagValue,
   projectTmuxConfig,
   resolveAgent,
   resolveUserConfigPath,
+  suppliedModulesFromFlags,
 } from "./launch-config.js";
 
 const READINESS_FAILURE_EXIT_CODE = 2;
@@ -188,10 +193,15 @@ export async function runPlaybookCli(options = {}) {
   // PBCLI-25/26: `--with <path>` overlays are launcher-owned — consumed
   // here, never forwarded to tmux-play, and incompatible with a raw
   // `--config` launch, which bypasses the composition they target.
+  // PBCLI-94 (DR-083): `--module <id>=<specifier>` is launcher-owned in the
+  // same way: consumed, never forwarded, and refused beside raw `--config`.
   let withPaths;
+  let modulePairs;
+  let modules;
   let forwardArgv;
   try {
     ({ withPaths, rest: forwardArgv } = extractWithFlags(argv));
+    ({ modulePairs, rest: forwardArgv } = extractModuleFlags(forwardArgv));
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -203,6 +213,22 @@ export async function runPlaybookCli(options = {}) {
     );
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
+  if (modulePairs.length > 0 && hasExplicitConfig(argv)) {
+    stderr.write(
+      "playbook: --module supplies a playbook module for the top-level " +
+        "config and cannot combine with a raw --config launch\n",
+    );
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+  try {
+    modules = suppliedModulesFromFlags(
+      modulePairs,
+      options.cwd ?? process.cwd(),
+    );
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
   const noProvision = forwardArgv.includes("--no-provision");
   forwardArgv = forwardArgv.filter((arg) => arg !== "--no-provision");
   if (noProvision && hasExplicitConfig(argv)) {
@@ -349,6 +375,7 @@ export async function runPlaybookCli(options = {}) {
       ? await loadSelectedLaunchPlanDataOnly({
           userConfigPath,
           overlayPaths: withPaths,
+          modules,
           structuralProjection: selectedRecord.structuralProjection,
           onNotice: (line) => stderr.write(line),
           env,
@@ -357,6 +384,7 @@ export async function runPlaybookCli(options = {}) {
       : await loadLaunchPlan({
           userConfigPath,
           overlayPaths: withPaths,
+          modules,
           env,
           homeDir: home,
           loadModule,
@@ -923,13 +951,17 @@ function helpText({
     ...sdkFailureLines,
     ...failures,
     "Usage:",
-    "  playbook [--with <path>]... [--no-provision] [--cwd <path>]",
-    "  playbook --session <id> [--with <path>]... [--no-provision]",
-    "  playbook --list [--with <path>]... [--no-provision]",
-    "  playbook --theme-diagnostics [--with <path>]... [--cwd <path>]",
+    "  playbook [--with <path>]... [--module <id>=<specifier>]...",
+    "           [--no-provision] [--cwd <path>]",
+    "  playbook --session <id> [--with <path>]...",
+    "           [--module <id>=<specifier>]... [--no-provision]",
+    "  playbook --list [--with <path>]... [--module <id>=<specifier>]...",
+    "           [--no-provision]",
+    "  playbook --theme-diagnostics [--with <path>]...",
+    "           [--module <id>=<specifier>]... [--cwd <path>]",
     "  playbook --config <path> [tmux-play arguments...]",
-    "  playbook run [--with <path>]... [--no-provision] [--json]",
-    "               [--verbose] [--] [input]",
+    "  playbook run [--with <path>]... [--module <id>=<specifier>]...",
+    "               [--no-provision] [--json] [--verbose] [--] [input]",
     "  playbook run (--continue | --session <id>) [reply]",
     "  playbook run --session <id> --retry-uncertain",
     "  playbook run --session <id> --discard-uncertain",
@@ -947,6 +979,11 @@ function helpText({
     "  the default config) for a fresh launch or compatible ordinary reopen —",
     "  maps merge recursively, other values replace, later files win, and the",
     "  default config file is never modified.",
+    "  --module <id>=<specifier> supplies playbook <id>'s registry module",
+    "  ahead of its playbooks.<id>.from (repeatable, one per id); a relative",
+    "  path resolves against the current directory, and the module is never",
+    "  written back to your config files. Without --module or from, a",
+    "  reopened session uses the module it already records.",
     "  --no-provision keeps configured filesystem registries read-only;",
     "  any missing engine links remain a launch error.",
     "  `playbook run --verbose` prints Captain telemetry topics to stderr.",

package/reference/sdlc/code.playbook/bin/run.js

@@ -39,12 +39,14 @@ import {
   invalidRegistryEntryReason,
   loadLaunchPlan,
   loadSelectedLaunchPlanDataOnly,
+  parseModuleFlagValue,
   projectHostAgent,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
   resolveFormerUserConfigPaths,
   resolveUserConfigPath,
   snapshotRegistryEntry,
+  suppliedModulesFromFlags,
 } from "./launch-config.js";
 import { prepareConfiguredRegistries } from "./provision.js";
 import {
@@ -122,6 +124,12 @@ export async function runPlaybookRun(options = {}) {
   const recovering = args.retryUncertain || args.discardUncertain;
   const continuing = args.continue || args.sessionId !== undefined;
   let input = args.input;
+  // PBCLI-94 (DR-083): a relative supplied module resolves against the
+  // invocation's working directory before the loader sees it.
+  const modules = suppliedModulesFromFlags(
+    args.modulePairs,
+    options.cwd ?? process.cwd(),
+  );
 
   // PBCLI-18/40: a fresh piped producer is drained before config,
   // preparation, import, or readiness. Continuations first inspect the
@@ -369,6 +377,7 @@ export async function runPlaybookRun(options = {}) {
         ? await loadSelectedLaunchPlanDataOnly({
             userConfigPath,
             overlayPaths: args.withPaths,
+            modules,
             structuralProjection: priorRecord.structuralProjection,
             onNotice: (line) => configNotices.push(line),
             env,
@@ -377,6 +386,7 @@ export async function runPlaybookRun(options = {}) {
         : await loadLaunchPlan({
             userConfigPath,
             overlayPaths: args.withPaths,
+            modules,
             env,
             homeDir: home,
             loadModule,
@@ -1561,6 +1571,7 @@ export function parseRunArgs(argv) {
   const parsed = {
     input: undefined,
     withPaths: [],
+    modulePairs: [],
     noProvision: false,
     json: false,
     verbose: false,
@@ -1625,6 +1636,18 @@ export function parseRunArgs(argv) {
       const value = arg.slice("--with=".length);
       if (value === "") throw new Error("--with needs a value");
       parsed.withPaths.push(value);
+    } else if (arg === "--module" || arg.startsWith("--module=")) {
+      // PBCLI-94 (DR-083): one `<id>=<specifier>` per playbook id.
+      const pair = parseModuleFlagValue(
+        arg === "--module" ? argv[index + 1] : arg.slice("--module=".length),
+      );
+      if (arg === "--module") index += 1;
+      if (parsed.modulePairs.some(([id]) => id === pair[0])) {
+        throw new Error(
+          `--module names playbook ${JSON.stringify(pair[0])} more than once`,
+        );
+      }
+      parsed.modulePairs.push(pair);
     } else if (
       RETIRED_FLAGS.has(arg) ||
       [...RETIRED_FLAGS].some((flag) => arg.startsWith(`${flag}=`))
@@ -1681,6 +1704,12 @@ export function parseRunArgs(argv) {
   ) {
     throw new Error("--with is unavailable during uncertain-turn recovery");
   }
+  if (
+    (parsed.retryUncertain || parsed.discardUncertain) &&
+    parsed.modulePairs.length > 0
+  ) {
+    throw new Error("--module is unavailable during uncertain-turn recovery");
+  }
   if (
     parsed.sessionId !== undefined &&
     !SESSION_ID_PATTERN.test(parsed.sessionId)
@@ -1928,10 +1957,11 @@ async function writeStream(stream, text) {
 function runHelpText(userConfigPath) {
   return [
     "Usage:",
-    "  playbook run [--with <path>]... [--no-provision] [--json]",
-    "               [--verbose] [--] [input]",
+    "  playbook run [--with <path>]... [--module <id>=<specifier>]...",
+    "               [--no-provision] [--json] [--verbose] [--] [input]",
     "  playbook run (--continue | --session <id>) [--with <path>]...",
-    "               [--no-provision] [--json] [--verbose] [--] [reply]",
+    "               [--module <id>=<specifier>]... [--no-provision] [--json]",
+    "               [--verbose] [--] [reply]",
     "  playbook run --session <id> --retry-uncertain [--no-provision]",
     "  playbook run --session <id> --discard-uncertain",
     "",
@@ -1959,6 +1989,10 @@ function runHelpText(userConfigPath) {
     "",
     "Options:",
     "  --with <path>    overlay a generic config fragment (repeatable)",
+    "  --module <id>=<specifier>",
+    "                   supply playbook <id>'s module ahead of its",
+    "                   playbooks.<id>.from (repeatable, one per id); a",
+    "                   continuation without either uses the stored module",
     "  --no-provision   do not provision thin filesystem registry engines",
     "  --continue       prefer this working directory, else global newest",
     "  --session <id>   reply to one durable Captain session UUID",

package/reference/sdlc/code.playbook/session-host.d.ts

@@ -43,8 +43,15 @@ export declare function installRetainedGenerationsForLaunch(options: {
 export declare function executionConfigFromPlan(plan: any): SessionExecutionProjection;
 export declare function validateFrozenExecutionConfig(structural: SessionStructuralProjection, execution: SessionExecutionProjection, dependencies: { loadModule: (specifier: string) => Promise<any>; prepareRegistryModule?: (request: {id: string; from: string; authoredFrom: string}) => Promise<string | void> }): Promise<SessionExecutionProjection>;
 export declare function driveHeadlessCaptainTurn(options: any): Promise<any>;
-export declare function normalizeLaunchPlan(top: any, options?: any): Promise<any>;
-export declare function loadLaunchPlan(options: any): Promise<any>;
+/** Playbook id to registry module specifier, supplied at launch ahead of `playbooks.<id>.from` (DR-083). */
+export type PlaybookModuleLocations = Readonly<Record<string, string>>;
+export interface LaunchPlanModuleOptions {
+  /** Absolute paths become file URLs; file URLs and package specifiers are kept; relative paths are refused. */
+  readonly modules?: PlaybookModuleLocations;
+  readonly [key: string]: any;
+}
+export declare function normalizeLaunchPlan(top: any, options?: LaunchPlanModuleOptions): Promise<any>;
+export declare function loadLaunchPlan(options: LaunchPlanModuleOptions): Promise<any>;
 export declare function composeGenericConfig(top: any, loadModule: (specifier: string) => Promise<any>, configPath?: string): Promise<any>;
 export declare function projectTmuxConfig(plan: any): any;
 export declare function resolveLaunchSessionsDir(options: any): string;