@puddle-code/cli 0.2.24 → 0.3.1

package/CHANGELOG.md

@@ -4,8 +4,13 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
 
 # Changelog
 
-## [0.2.24] — 2026-10-14
+## [0.3.1] — 2026-10-14
+
+### Changed
+
+- Rename the puddlang executable to `pudl` across npm, standalone installers and command examples; retain the puddlang language/API name.
+- Suppress desktop notifications only during recent typing, pasting or clicking in the notifying session when focused delivery is disabled; idle windows and other sessions no longer silence alerts.
 
 ### Fixed
 
-- macOS releases without signing secrets unset the empty certificate environment before ad-hoc packaging, preventing electron-builder from treating the desktop directory as a certificate file. Desktop packaging leaves publication to the release job.
+- Activate the exact session tab on desktop notification clicks, including when a file hides its terminal under the same URL, and open sessions without an existing tab.

package/README.md

@@ -29,6 +29,10 @@ installer (replace the example host):
 curl -fsSL https://app.example.com/install.sh | sh
 ```
 
+The CLI also includes `pudl`, which runs puddlang programmes for coder/reviewer
+loops and other agent workflows through the shell or stdio MCP. See the
+[puddlang guide](docs/puddlang.md) for setup, examples and initial limitations.
+
 This installs the CLI under `~/.local/share/puddle/cli` and its launcher at
 `~/.local/bin/puddle`. Add `~/.local/bin` to your `PATH` if the installer asks.
 The standalone releases support Linux x64/arm64 and macOS arm64. The script and

package/dist/host-control.mjs

@@ -16188,6 +16188,153 @@ var connectorNotificationSchema = external_exports.object({
 var pushDispatchResultSchema = external_exports.object({ accepted: external_exports.number().int().nonnegative(), failed: external_exports.number().int().nonnegative() }).strict();
 var pushPreferenceResultSchema = external_exports.object({ enabled: external_exports.boolean() }).strict();
 
+// ../shared/src/api/puddlang.ts
+var PUDDLANG_MAX_SOURCE = 256 * 1024;
+var sourceSchema = external_exports.string().min(1).max(PUDDLANG_MAX_SOURCE).refine(
+  (source) => new TextEncoder().encode(source).length <= PUDDLANG_MAX_SOURCE,
+  "Source exceeds 256 KiB"
+);
+var puddlangSpawnSchema = external_exports.object({
+  agent: external_exports.string().min(1).max(100),
+  account: external_exports.union([external_exports.string().min(1).max(100), external_exports.number().int().positive()]).optional(),
+  project: external_exports.string().min(1).max(200).optional(),
+  worktree: external_exports.string().min(1).max(4096).optional(),
+  path: external_exports.string().min(1).max(4096).optional(),
+  title: external_exports.string().min(1).max(200).optional()
+}).refine((v) => Boolean(v.path) !== Boolean(v.project), "Choose path or project").refine((v) => !v.path || !v.worktree, "worktree requires project");
+var puddlangHandleSchema = external_exports.object({ runtime_id: external_exports.uuid(), session_id: sessionId });
+var puddlangAskSchema = external_exports.object({
+  prompt: external_exports.string().min(1).max(128 * 1024),
+  output_schema: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangStartSchema = external_exports.object({
+  id: external_exports.uuid(),
+  source: sourceSchema,
+  input: external_exports.unknown().optional(),
+  accounts: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number().int().positive()])).default({}),
+  max_turns: external_exports.number().int().min(1).max(1e3).default(50),
+  max_agents: external_exports.number().int().min(1).max(32).default(8),
+  timeout_ms: external_exports.number().int().min(1e3).max(24 * 60 * 60 * 1e3).default(60 * 60 * 1e3)
+});
+var puddlangRunSchema = external_exports.object({
+  id: external_exports.uuid(),
+  profile_id: profileId,
+  source_hash: external_exports.string(),
+  status: external_exports.enum(["running", "completed", "failed", "cancelled", "interrupted"]),
+  result: external_exports.unknown().nullable(),
+  error: external_exports.string().nullable(),
+  created_at: external_exports.string(),
+  updated_at: external_exports.string()
+});
+var puddlangEventSchema = external_exports.object({
+  sequence: external_exports.number().int(),
+  run_id: external_exports.uuid(),
+  type: external_exports.string(),
+  data: external_exports.unknown(),
+  created_at: external_exports.string()
+});
+var puddlangEventsSchema = external_exports.object({ events: external_exports.array(puddlangEventSchema) });
+var puddlangOperationSchema = external_exports.discriminatedUnion("op", [
+  external_exports.object({ op: external_exports.literal("spawn"), options: puddlangSpawnSchema }),
+  external_exports.object({ op: external_exports.literal("attach"), reference: external_exports.string().min(1).max(100) }),
+  external_exports.object({ op: external_exports.literal("ask"), handle: puddlangHandleSchema, request: puddlangAskSchema }),
+  external_exports.object({ op: external_exports.literal("stop"), handle: puddlangHandleSchema })
+]);
+var puddlangRunnerMessageSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("operation"),
+    id: external_exports.number().int(),
+    operation: puddlangOperationSchema
+  }),
+  external_exports.object({
+    type: external_exports.literal("finished"),
+    result: external_exports.unknown().optional(),
+    error: external_exports.string().max(8192).optional()
+  })
+]);
+var puddlangRunnerInputSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("start"),
+    source: sourceSchema,
+    input: external_exports.unknown().optional()
+  }),
+  external_exports.object({
+    type: external_exports.literal("reply"),
+    id: external_exports.number().int(),
+    value: external_exports.unknown().optional(),
+    error: external_exports.string().optional()
+  })
+]);
+var puddlangContextSchema = external_exports.object({
+  profile: external_exports.object({ id: profileId, name: external_exports.string() }),
+  projects: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), path: external_exports.string() })),
+  accounts: external_exports.array(
+    external_exports.object({ id: external_exports.number(), label: external_exports.string(), agent: external_exports.string(), logged_in: external_exports.boolean() })
+  ),
+  agents: external_exports.array(external_exports.object({ id: external_exports.string(), scripted_turns: external_exports.boolean() }))
+});
+
+// ../shared/src/api/puddlang-mcp.ts
+var puddlangMcpRequestSchema = external_exports.object({
+  jsonrpc: external_exports.literal("2.0"),
+  id: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+  method: external_exports.string(),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangMcpCallSchema = external_exports.object({
+  name: external_exports.string(),
+  arguments: external_exports.unknown().optional()
+});
+var puddlangMcpRunSchema = puddlangStartSchema;
+var puddlangMcpIdSchema = external_exports.object({ id: external_exports.uuid() });
+var puddlangMcpEventsSchema = puddlangMcpIdSchema.extend({
+  after: external_exports.number().int().nonnegative().default(0)
+});
+var puddlangMcpEmptySchema = external_exports.object({}).strict();
+var definitions = [
+  [
+    "puddlang_context",
+    "List this host profile, projects, accounts and supported agents.",
+    puddlangMcpEmptySchema,
+    true
+  ],
+  [
+    "puddlang_run",
+    'Execute a trusted single-file TypeScript programme on the host. Imports: puddlang (spawn, attach, input, z), zod, node: built-ins. Returns immediately with a durable run id; use status/events. Supply a fresh UUID id, or reuse it with identical input to recover an uncertain submission. spawn({agent:"codex",project:"name",account:"label"}); await agent.ask("task"); export default result. Supports structured ask({prompt,input,schema:z.object(...)}) and agent.stop().',
+    puddlangMcpRunSchema,
+    false
+  ],
+  [
+    "puddlang_status",
+    "Read a run and its final default export, if finished.",
+    puddlangMcpIdSchema,
+    true
+  ],
+  [
+    "puddlang_events",
+    "Read up to 100 events after a sequence; paginate until empty.",
+    puddlangMcpEventsSchema,
+    true
+  ],
+  [
+    "puddlang_cancel",
+    "Cancel a run, interrupt its pending asks, and stop agents it created. Attached agents are retained.",
+    puddlangMcpIdSchema,
+    false
+  ]
+];
+var puddlangMcpTools = definitions.map(([name, description, schema, readOnlyHint]) => ({
+  name,
+  description,
+  inputSchema: external_exports.toJSONSchema(schema, { io: "input" }),
+  annotations: {
+    readOnlyHint,
+    destructiveHint: !readOnlyHint,
+    idempotentHint: true,
+    openWorldHint: !readOnlyHint
+  }
+}));
+
 // ../shared/src/node/security.ts
 import { createHash, randomBytes } from "node:crypto";
 import {

package/dist/index.js

@@ -3925,7 +3925,7 @@ import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
 
 // ../shared/src/protocol.ts
-var PROTOCOL_VERSION = { major: 22, minor: 5 };
+var PROTOCOL_VERSION = { major: 23, minor: 0 };
 
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -20108,6 +20108,153 @@ var connectorNotificationSchema = external_exports.object({
 var pushDispatchResultSchema = external_exports.object({ accepted: external_exports.number().int().nonnegative(), failed: external_exports.number().int().nonnegative() }).strict();
 var pushPreferenceResultSchema = external_exports.object({ enabled: external_exports.boolean() }).strict();
 
+// ../shared/src/api/puddlang.ts
+var PUDDLANG_MAX_SOURCE = 256 * 1024;
+var sourceSchema = external_exports.string().min(1).max(PUDDLANG_MAX_SOURCE).refine(
+  (source) => new TextEncoder().encode(source).length <= PUDDLANG_MAX_SOURCE,
+  "Source exceeds 256 KiB"
+);
+var puddlangSpawnSchema = external_exports.object({
+  agent: external_exports.string().min(1).max(100),
+  account: external_exports.union([external_exports.string().min(1).max(100), external_exports.number().int().positive()]).optional(),
+  project: external_exports.string().min(1).max(200).optional(),
+  worktree: external_exports.string().min(1).max(4096).optional(),
+  path: external_exports.string().min(1).max(4096).optional(),
+  title: external_exports.string().min(1).max(200).optional()
+}).refine((v) => Boolean(v.path) !== Boolean(v.project), "Choose path or project").refine((v) => !v.path || !v.worktree, "worktree requires project");
+var puddlangHandleSchema = external_exports.object({ runtime_id: external_exports.uuid(), session_id: sessionId });
+var puddlangAskSchema = external_exports.object({
+  prompt: external_exports.string().min(1).max(128 * 1024),
+  output_schema: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangStartSchema = external_exports.object({
+  id: external_exports.uuid(),
+  source: sourceSchema,
+  input: external_exports.unknown().optional(),
+  accounts: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number().int().positive()])).default({}),
+  max_turns: external_exports.number().int().min(1).max(1e3).default(50),
+  max_agents: external_exports.number().int().min(1).max(32).default(8),
+  timeout_ms: external_exports.number().int().min(1e3).max(24 * 60 * 60 * 1e3).default(60 * 60 * 1e3)
+});
+var puddlangRunSchema = external_exports.object({
+  id: external_exports.uuid(),
+  profile_id: profileId,
+  source_hash: external_exports.string(),
+  status: external_exports.enum(["running", "completed", "failed", "cancelled", "interrupted"]),
+  result: external_exports.unknown().nullable(),
+  error: external_exports.string().nullable(),
+  created_at: external_exports.string(),
+  updated_at: external_exports.string()
+});
+var puddlangEventSchema = external_exports.object({
+  sequence: external_exports.number().int(),
+  run_id: external_exports.uuid(),
+  type: external_exports.string(),
+  data: external_exports.unknown(),
+  created_at: external_exports.string()
+});
+var puddlangEventsSchema = external_exports.object({ events: external_exports.array(puddlangEventSchema) });
+var puddlangOperationSchema = external_exports.discriminatedUnion("op", [
+  external_exports.object({ op: external_exports.literal("spawn"), options: puddlangSpawnSchema }),
+  external_exports.object({ op: external_exports.literal("attach"), reference: external_exports.string().min(1).max(100) }),
+  external_exports.object({ op: external_exports.literal("ask"), handle: puddlangHandleSchema, request: puddlangAskSchema }),
+  external_exports.object({ op: external_exports.literal("stop"), handle: puddlangHandleSchema })
+]);
+var puddlangRunnerMessageSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("operation"),
+    id: external_exports.number().int(),
+    operation: puddlangOperationSchema
+  }),
+  external_exports.object({
+    type: external_exports.literal("finished"),
+    result: external_exports.unknown().optional(),
+    error: external_exports.string().max(8192).optional()
+  })
+]);
+var puddlangRunnerInputSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("start"),
+    source: sourceSchema,
+    input: external_exports.unknown().optional()
+  }),
+  external_exports.object({
+    type: external_exports.literal("reply"),
+    id: external_exports.number().int(),
+    value: external_exports.unknown().optional(),
+    error: external_exports.string().optional()
+  })
+]);
+var puddlangContextSchema = external_exports.object({
+  profile: external_exports.object({ id: profileId, name: external_exports.string() }),
+  projects: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), path: external_exports.string() })),
+  accounts: external_exports.array(
+    external_exports.object({ id: external_exports.number(), label: external_exports.string(), agent: external_exports.string(), logged_in: external_exports.boolean() })
+  ),
+  agents: external_exports.array(external_exports.object({ id: external_exports.string(), scripted_turns: external_exports.boolean() }))
+});
+
+// ../shared/src/api/puddlang-mcp.ts
+var puddlangMcpRequestSchema = external_exports.object({
+  jsonrpc: external_exports.literal("2.0"),
+  id: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+  method: external_exports.string(),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var puddlangMcpCallSchema = external_exports.object({
+  name: external_exports.string(),
+  arguments: external_exports.unknown().optional()
+});
+var puddlangMcpRunSchema = puddlangStartSchema;
+var puddlangMcpIdSchema = external_exports.object({ id: external_exports.uuid() });
+var puddlangMcpEventsSchema = puddlangMcpIdSchema.extend({
+  after: external_exports.number().int().nonnegative().default(0)
+});
+var puddlangMcpEmptySchema = external_exports.object({}).strict();
+var definitions = [
+  [
+    "puddlang_context",
+    "List this host profile, projects, accounts and supported agents.",
+    puddlangMcpEmptySchema,
+    true
+  ],
+  [
+    "puddlang_run",
+    'Execute a trusted single-file TypeScript programme on the host. Imports: puddlang (spawn, attach, input, z), zod, node: built-ins. Returns immediately with a durable run id; use status/events. Supply a fresh UUID id, or reuse it with identical input to recover an uncertain submission. spawn({agent:"codex",project:"name",account:"label"}); await agent.ask("task"); export default result. Supports structured ask({prompt,input,schema:z.object(...)}) and agent.stop().',
+    puddlangMcpRunSchema,
+    false
+  ],
+  [
+    "puddlang_status",
+    "Read a run and its final default export, if finished.",
+    puddlangMcpIdSchema,
+    true
+  ],
+  [
+    "puddlang_events",
+    "Read up to 100 events after a sequence; paginate until empty.",
+    puddlangMcpEventsSchema,
+    true
+  ],
+  [
+    "puddlang_cancel",
+    "Cancel a run, interrupt its pending asks, and stop agents it created. Attached agents are retained.",
+    puddlangMcpIdSchema,
+    false
+  ]
+];
+var puddlangMcpTools = definitions.map(([name, description, schema, readOnlyHint]) => ({
+  name,
+  description,
+  inputSchema: external_exports.toJSONSchema(schema, { io: "input" }),
+  annotations: {
+    readOnlyHint,
+    destructiveHint: !readOnlyHint,
+    idempotentHint: true,
+    openWorldHint: !readOnlyHint
+  }
+}));
+
 // src/lib/transport/local.ts
 import { spawn } from "node:child_process";
 import { copyFileSync, mkdirSync, readFileSync } from "node:fs";
@@ -21646,7 +21793,7 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { dirname as dirname4, join as join5 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function cliVersion() {
-  if (true) return "0.2.24";
+  if (true) return "0.3.1";
   const here = dirname4(fileURLToPath2(import.meta.url));
   for (const candidate of [
     join5(here, "..", "..", "package.json"),
@@ -22043,7 +22190,9 @@ var RELEASE_PROTOCOLS = {
   "0.2.21": { major: 22, minor: 4 },
   "0.2.22": { major: 22, minor: 4 },
   "0.2.23": { major: 22, minor: 5 },
-  "0.2.24": { major: 22, minor: 5 }
+  "0.2.24": { major: 22, minor: 5 },
+  "0.3.0": { major: 23, minor: 0 },
+  "0.3.1": { major: 23, minor: 0 }
 };
 function validProtocol(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -24305,7 +24454,7 @@ init_types();
 import { spawn as spawn6 } from "node:child_process";
 import { existsSync as existsSync5, lstatSync as lstatSync2, readFileSync as readFileSync9, realpathSync as realpathSync2 } from "node:fs";
 import { mkdir as mkdir2, readFile as readFile2, rm as rm2, unlink } from "node:fs/promises";
-import { dirname as dirname9, isAbsolute, join as join15, resolve as resolve5 } from "node:path";
+import { basename, dirname as dirname9, isAbsolute, join as join15, resolve as resolve5 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function standaloneInstallation(entryFile = fileURLToPath4(import.meta.url), execPath = process.execPath) {
   const release = resolve5(dirname9(entryFile), "..");
@@ -24313,9 +24462,14 @@ function standaloneInstallation(entryFile = fileURLToPath4(import.meta.url), exe
   try {
     const root = resolve5(release, "..", "..");
     const record2 = JSON.parse(readFileSync9(join15(root, "installation.json"), "utf8"));
-    if (readFileSync9(join15(release, "STANDALONE"), "utf8").trim() !== "puddle-cli" || readFileSync9(join15(root, "INSTALLATION"), "utf8").trim() !== "puddle-cli" || dirname9(release) !== join15(root, "versions") || realpathSync2(release) !== release || realpathSync2(execPath) !== join15(release, "bin/node") || record2.kind !== "puddle-cli" || typeof record2.launcher !== "string" || !isAbsolute(record2.launcher))
+    if (readFileSync9(join15(release, "STANDALONE"), "utf8").trim() !== "puddle-cli" || readFileSync9(join15(root, "INSTALLATION"), "utf8").trim() !== "puddle-cli" || dirname9(release) !== join15(root, "versions") || realpathSync2(release) !== release || realpathSync2(execPath) !== join15(release, "bin/node") || record2.kind !== "puddle-cli" || typeof record2.launcher !== "string" || !isAbsolute(record2.launcher) || record2.scriptLauncher !== void 0 && record2.scriptLauncher !== join15(dirname9(record2.launcher), "pudl") && record2.scriptLauncher !== join15(dirname9(record2.launcher), "puddlang"))
       throw new Error("Installation metadata does not match this CLI");
-    return { root, release, launcher: record2.launcher };
+    return {
+      root,
+      release,
+      launcher: record2.launcher,
+      ...typeof record2.scriptLauncher === "string" ? { scriptLauncher: record2.scriptLauncher } : {}
+    };
   } catch {
     throw new CliError(
       "not_installed",
@@ -24349,8 +24503,8 @@ function upgradeStandaloneCli(installation, version2, repo) {
     });
   });
 }
-function standaloneLauncher(root) {
-  const quoted = `'${join15(root, "current/puddle").replaceAll("'", "'\\''")}'`;
+function standaloneLauncher(root, command = "puddle") {
+  const quoted = `'${join15(root, `current/${command}`).replaceAll("'", "'\\''")}'`;
   return `#!/bin/sh
 # puddle standalone launcher
 exec ${quoted} "$@"
@@ -24366,6 +24520,15 @@ async function removeStandaloneCli(installation) {
   try {
     if (lstatSync2(installation.launcher).isSymbolicLink() || await readFile2(installation.launcher, "utf8") !== standaloneLauncher(installation.root))
       throw new CliError("not_installed", "the CLI launcher was replaced; refusing removal");
+    if (installation.scriptLauncher && existsSync5(installation.scriptLauncher)) {
+      const command = basename(installation.scriptLauncher);
+      if (command !== "pudl" && command !== "puddlang" || !lstatSync2(installation.scriptLauncher).isFile() || await readFile2(installation.scriptLauncher, "utf8") !== standaloneLauncher(installation.root, command))
+        throw new CliError(
+          "not_installed",
+          `the ${command} launcher was replaced; refusing removal`
+        );
+      await unlink(installation.scriptLauncher);
+    }
     await unlink(installation.launcher);
     await rm2(installation.root, { recursive: true, force: true });
   } finally {

package/dist/install-cli.sh

@@ -125,16 +125,29 @@ main() {
   done
   # Help loads the bundle without touching a daemon or user state.
   "$STAGE/puddle" --help >/dev/null || die "CLI smoke test failed"
+  if [ -f "$STAGE/pudl" ]; then
+    "$STAGE/pudl" --help >/dev/null || die "pudl smoke test failed"
+  elif [ -f "$STAGE/puddlang" ]; then
+    "$STAGE/puddlang" --help >/dev/null || die "puddlang smoke test failed"
+  fi
   "$STAGE/bin/node" --input-type=commonjs - "$PREFIX" "$BIN_DIR" "$STAGE" <<'NODE'
 const fs = require('node:fs'), path = require('node:path');
 const [root, binDir, stage] = process.argv.slice(2);
 const launcher = path.join(binDir, 'puddle');
 const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
 const wrapper = '#!/bin/sh\n# puddle standalone launcher\nexec ' + quote(path.join(root, 'current/puddle')) + ' "$@"\n';
+// Older archives remain installable; current releases provide only pudl.
+const scriptCommand = ['pudl', 'puddlang'].find((name) => fs.existsSync(path.join(stage, name)));
+const scriptLauncher = path.join(binDir, scriptCommand || 'pudl');
+const scriptWrapperFor = (name) => '#!/bin/sh\n# puddle standalone launcher\nexec ' + quote(path.join(root, 'current', name)) + ' "$@"\n';
+const scriptWrapper = scriptWrapperFor(scriptCommand || 'pudl');
+const hasScript = scriptCommand !== undefined;
 const stat = (p) => { try { return fs.lstatSync(p); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } };
 if (stat(launcher) && (!stat(launcher).isFile() || fs.readFileSync(launcher, 'utf8') !== wrapper)) {
   throw Error('Refusing to replace an unrelated launcher: ' + launcher + '; choose --bin-dir');
 }
+const ownsScript = stat(scriptLauncher)?.isFile() && fs.readFileSync(scriptLauncher, 'utf8') === scriptWrapper;
+if (hasScript && stat(scriptLauncher) && !ownsScript) throw Error('Refusing to replace an unrelated launcher: ' + scriptLauncher + '; choose --bin-dir');
 const current = path.join(root, 'current');
 if (stat(current) && !stat(current).isSymbolicLink()) throw Error('current must be a symlink');
 const record = path.join(root, 'installation.json');
@@ -144,14 +157,23 @@ if (stat(record)) {
 }
 const tmp = '.new-' + process.pid;
 try {
-  fs.writeFileSync(record + tmp, JSON.stringify({ kind: 'puddle-cli', launcher }) + '\n', { flag: 'wx', mode: 0o600 });
+  fs.writeFileSync(record + tmp, JSON.stringify({ kind: 'puddle-cli', launcher, ...(hasScript ? { scriptLauncher } : {}) }) + '\n', { flag: 'wx', mode: 0o600 });
   fs.writeFileSync(launcher + tmp, wrapper, { flag: 'wx', mode: 0o755 });
+  if (hasScript) fs.writeFileSync(scriptLauncher + tmp, scriptWrapper, { flag: 'wx', mode: 0o755 });
   fs.symlinkSync(path.relative(root, stage), current + tmp);
   fs.renameSync(record + tmp, record);
   fs.renameSync(launcher + tmp, launcher);
+  if (hasScript) fs.renameSync(scriptLauncher + tmp, scriptLauncher);
   fs.renameSync(current + tmp, current); // Activate only after every other write succeeds.
+  // Remove only exact wrappers owned by this installation when the command
+  // changes or a named older release does not contain a scripting command.
+  for (const name of ['pudl', 'puddlang']) {
+    if (name === scriptCommand) continue;
+    const obsolete = path.join(binDir, name);
+    if (stat(obsolete)?.isFile() && fs.readFileSync(obsolete, 'utf8') === scriptWrapperFor(name)) fs.unlinkSync(obsolete);
+  }
 } finally {
-  for (const file of [record + tmp, launcher + tmp, current + tmp]) fs.rmSync(file, { force: true });
+  for (const file of [record + tmp, launcher + tmp, scriptLauncher + tmp, current + tmp]) fs.rmSync(file, { force: true });
 }
 NODE
   STAGE="" # Published releases stay intact, including those serving live cockpits.