@sublang/playbook 17.4.0 → 17.5.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",