runlist 0.95.6 → 0.96.0

package/README.md

@@ -47,8 +47,8 @@ controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
 <!-- runlist:release:start -->
-CLI and desktop release version: **0.95.6**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.95.6).
+CLI and desktop release version: **0.96.0**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.96.0).
 Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
 <!-- runlist:release:end -->
 
@@ -652,6 +652,13 @@ operation:
 runlist baton @/tmp/resume.md
 ```
 
+Parent handoffs use `resume-<name>`. Delegated agents explicitly use
+`runlist baton --subagent <task-slug> @/tmp/resume.md` for `subagent-<task-slug>`.
+Under a parent-owned plan, use a distinct task slug that does not resolve to a
+plan. A child owning a dedicated plan can pass that plan with `--subagent`.
+Existing prompts keep their names. See `runlist baton --help` for prefix and
+replacement checks.
+
 Baton refuses when a handoff for the same work is already pending, so one piece
 of work never has two resume prompts. Inspect the pending handoff with
 `runlist prompts show <slug>`. Keep it if current; if stale, pass `--replace`

package/bin/runlist.mjs

@@ -1349,6 +1349,7 @@ Options:
   --note "why"           Append the reason to ## Version History (plan mode only)
   --message / --body     Inline body (one-liners; prefer @path or stdin)
   --force                Recover another session's plan (explicit path required)
+  --subagent             Save subagent-<name> instead of the parent default resume-<name>
   --replace              Replace exactly one pending handoff; archive its prior text
   --done                 Report a plan handoff done once next_step changed after the prompt was saved
   --json                 Structured repository/session/generated file result
@@ -1363,6 +1364,7 @@ The function returns argv; baton shell-quotes each argument before printing.
 Examples:
   runlist baton @/tmp/draft.md
   runlist baton checkout-fixes @/tmp/draft.md
+  runlist baton --subagent totals-review @/tmp/draft.md
   runlist baton docs/plans/auth.md @/tmp/draft.md
   runlist baton docs/plans/auth.md @/tmp/new-draft.md --replace
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
@@ -1388,7 +1390,14 @@ cooperating transaction:
   grant ownership. A live pickup-hook delivery lease blocks release and force
   takeover; hooks are at-least-once and deduplicate the stable operationId.
 
-Slug mode (no plan involved) saves resume-<slug> without a status change or
+Use --subagent for a delegated agent handoff, named subagent-<plan-slug> or
+subagent-<slug>. Under a parent-owned plan, pass a task-specific slug rather
+than releasing the parent plan. A child owning its own plan can hand it off.
+Matching prefixes are kept once; conflicting or nested prefixes are refused.
+Existing prompts keep their names. --subagent --replace refuses a parent-named
+handoff rather than reclassifying it.
+
+Slug mode (no plan involved) saves resume-<slug> by default without a status change or
 commit. A bare word that names a plan is treated as that plan.
 
 Baton saves nothing while a handoff for the same work is pending (resume-<name>,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.95.6",
+  "version": "0.96.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.95.6",
+  "version": "0.96.0",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -16,6 +16,7 @@ Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`.
 - Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
 - Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.
 - For a handoff, write a concrete resume draft, then run `runlist baton [<plan-or-slug>] @<draft-file>`. An owned plan is released in the same operation. If a handoff for that work is pending, inspect it with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
+- **Subagent handoffs:** use `runlist baton --subagent <task-slug> @/tmp/draft.md` to save `subagent-<task-slug>`. Under a parent-owned plan, choose a distinct task slug that does not resolve to a plan; do not release the parent's claim. A child owning a dedicated plan can use `runlist baton --subagent <plan-file> @/tmp/draft.md`. Parent-session batons keep the default `resume-*` naming. Matching prefixes are kept once; conflicting prefixes are refused. Existing prompts keep their names, and `--subagent --replace` refuses a parent-prefixed prompt.
 - Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. For read-only triage, use `runlist prompts show <file>` or `runlist prompts show --all`; never open pending prompts with a file reader or `cat`.
 - Pending prompts are session-local. Commit the tracked plan or source files named by baton, not `docs/prompts/*.md`.
 - Create a document with `runlist new <type> <name> @<draft-file>`. A draft starting with frontmatter can supply scaffold fields; `type` is fixed by the command.

package/src/baton.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
-import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
+import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput, slugify } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { handoffNotDoneLine, recordPendingHandoff, runBatonDone } from './handoff-record.mjs';
@@ -123,6 +123,7 @@ export async function runBaton(argv, config, opts = {}) {
   let force = false;
   let replace = false;
   let done = false;
+  let subagent = false;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -132,6 +133,7 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--force') { force = true; continue; }
     if (a === '--replace') { replace = true; continue; }
     if (a === '--done') { done = true; continue; }
+    if (a === '--subagent') { subagent = true; continue; }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
     die(`Unknown flag for \`runlist baton\`: ${a}`);
@@ -199,12 +201,30 @@ export async function runBaton(argv, config, opts = {}) {
     }
   }
 
-  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
-  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
+  const nameBase = slugify(planPath ? path.basename(planPath, '.md') : promptSlug);
+  const handoffPrefix = subagent ? 'subagent-' : 'resume-';
+  const recognizedPrefix = /^(resume-|subagent-)/.exec(nameBase)?.[0];
+  if (recognizedPrefix && recognizedPrefix !== handoffPrefix) {
+    die(`Nothing saved: ${nameBase} conflicts with ${subagent ? '--subagent' : 'the parent handoff default'}. Use an unprefixed name or ${handoffPrefix}<name>${subagent ? ', or omit --subagent for a parent handoff' : ', or pass --subagent for a child handoff'}.`);
+  }
+  const unprefixed = recognizedPrefix ? nameBase.slice(handoffPrefix.length) : nameBase;
+  if (!unprefixed || /^(resume-|subagent-)/.test(unprefixed)) {
+    die('Nothing saved: use a nonempty handoff name with at most one resume- or subagent- prefix.');
+  }
+  const slugBase = `${handoffPrefix}${unprefixed}`;
   let replacement = null;
+  let alternatePromptPath = null;
   const resolvePending = () => {
     const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
     const pending = pendingHandoffs(target.filePath, planPath, config);
+    if (planPath) {
+      const alternateSlug = `${subagent ? 'resume-' : 'subagent-'}${unprefixed}`;
+      alternatePromptPath = preparePromptDocument(alternateSlug, body, config, { dryRun: true }).filePath;
+      if (existsSync(alternatePromptPath)) {
+        const alternate = toRepoPath(alternatePromptPath, config.repoRoot);
+        if (!pending.includes(alternate)) pending.push(alternate);
+      }
+    }
     if (!replace) {
       if (pending.length) refusePendingHandoff(pending);
       return;
@@ -214,6 +234,9 @@ export async function runBaton(argv, config, opts = {}) {
       die(`Nothing replaced: --replace requires exactly one pending handoff. ${detail}`);
     }
     const oldRepoPath = pending[0];
+    if (subagent && /^resume-/i.test(path.basename(oldRepoPath))) {
+      die(`Nothing replaced: ${oldRepoPath} is a parent handoff. Inspect it with \`runlist prompts show ${path.basename(oldRepoPath, '.md')}\`; use a separate task slug for the child handoff, or omit --subagent to refresh the parent handoff.`);
+    }
     const oldPath = authorizeManagedSource(path.resolve(config.repoRoot, oldRepoPath), config, { kind: 'Baton replacement source' }).path;
     const oldRaw = readFileSync(oldPath, 'utf8');
     const { frontmatter, body: oldBody } = extractFrontmatter(oldRaw);
@@ -344,8 +367,8 @@ export async function runBaton(argv, config, opts = {}) {
         throw err;
       }
     }
-    createdSlug = promptName;
     promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
+    createdSlug = path.basename(promptRepoPath, '.md');
   } else {
     const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
     const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, dryRun });
@@ -361,15 +384,18 @@ export async function runBaton(argv, config, opts = {}) {
         testHooks: opts.testHooks,
         additionalUpdates: dryRun ? [] : mutation.updates,
         creations: dryRun ? [] : replacement ? mutation.creations : [{ path: prepared.filePath, content: prepared.content }],
-        guards: dryRun ? [] : [...mutation.guards, ...(planGuard ? [planGuard] : [])],
+        guards: dryRun ? [] : [
+          ...mutation.guards, ...(planGuard ? [planGuard] : []),
+          ...(!replacement && alternatePromptPath ? [{ path: alternatePromptPath, absent: true }] : []),
+        ],
         deferIndex: true,
       });
     } catch (err) {
       if (/Destination already exists|File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
       throw err;
     }
-    createdSlug = prepared.slug;
     promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
+    createdSlug = path.basename(promptRepoPath, '.md');
     statusChanged = oldStatus !== status;
     if (!dryRun && !replacement) {
       try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }

package/src/commands.mjs

@@ -140,7 +140,7 @@ const definitions = [
   ], { aliases: ['prompt'] }),
   command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
-  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--replace'), flag('--done'), flag('--json')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--replace'), flag('--done'), flag('--subagent'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
     form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),

package/src/hud.mjs

@@ -294,6 +294,7 @@ export function buildHud(config) {
 const SUBAGENT_PRIMER = [
   'runlist manages this repo\'s plans/docs/prompts (markdown + YAML frontmatter).',
   'Verbs: plans|briefing | query <filters> | use [<file>] | set <status> <file> | new <type> <slug> | archive <file>.',
+  'Child handoff: `runlist baton --subagent <task-slug> @<draft-file>` saves subagent-<task-slug>. Use a task slug under a parent-owned plan; release only your own plan. Parent batons default to resume-<name>.',
   'Claims: `runlist doctor --claims` lists which session holds each plan; `--apply` releases the ones whose session is gone.',
   'Do NOT: cat/read a docs/prompts/*.md (use `runlist use <file>` — archive/claim commits before at-most-once output);',
   'git add/commit a prompt (they are session-local, often gitignored); hand-edit a `status:` field (use `runlist set`).',