@sublang/playbook 17.4.1 → 17.6.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.6.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",
@@ -81,6 +81,8 @@
     "reference/sdlc/code.playbook/session-store.d.ts",
     "reference/sdlc/code.playbook/host-capabilities.js",
     "reference/sdlc/code.playbook/host-capabilities.d.ts",
+    "reference/sdlc/code.playbook/machine-identity.js",
+    "reference/sdlc/code.playbook/machine-identity.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
@@ -89,6 +91,8 @@
     "reference/sdlc/code.playbook/bin/interactive-session.js",
     "reference/sdlc/code.playbook/bin/replay-observer.js",
     "reference/sdlc/code.playbook/bin/session-store.js",
+    "reference/sdlc/code.playbook/bin/private-paths.js",
+    "reference/sdlc/code.playbook/bin/machine-identity.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
     "reference/sdlc/code.playbook/bin/repository-effects.js",
@@ -201,6 +205,10 @@
       "types": "./reference/sdlc/code.playbook/host-capabilities.d.ts",
       "default": "./reference/sdlc/code.playbook/host-capabilities.js"
     },
+    "./machine-identity": {
+      "types": "./reference/sdlc/code.playbook/machine-identity.d.ts",
+      "default": "./reference/sdlc/code.playbook/machine-identity.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",

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,
       );
     }