runlist 0.98.2 → 0.99.0

package/README.md

@@ -71,8 +71,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.98.2**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.98.2).
+CLI and desktop release version: **0.99.0**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.99.0).
 Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
 <!-- runlist:release:end -->
 
@@ -803,6 +803,12 @@ excludes session prompts from `paths`.
 Saved prompts are local session state. Consume them with `runlist use`; inspect
 without consuming via `runlist prompts show`. Consuming a baton prompt also claims
 its plan; `runlist use --no-claim` reads and archives it without starting the plan.
+Only an agent session consumes: Claude Code, Codex, OpenCode, or a shell with
+`RUNLIST_SESSION_ID` set. In a plain terminal, `runlist use` prints the body and a
+closing line naming the `runlist prompts use <path>` the session runs, and leaves
+the prompt pending and its plan unclaimed. So `claude "$(runlist use)"` starts a
+session that consumes the prompt itself, and a session that never starts takes
+nothing.
 
 New plans are created `planned`; `runlist use` starts one, and
 `runlist new plan <name> --status <status>` sets a different starting status.

package/bin/runlist.mjs

@@ -119,7 +119,8 @@ Common commands:
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
   use [<file-or-slug>]  Open a doc by type: prompt → consume, plan → start, doc → read
-                        (no file: consume oldest pending prompt)
+                        (no file: consume oldest pending prompt; outside an
+                        agent session a prompt is printed, not consumed)
   baton [<plan>|<slug>] @<draft-file>
                         Save a resume prompt (+ release the plan, if one is in-session)
   archive <file>        Close out a plan (status → archived, move, update refs)
@@ -422,6 +423,8 @@ prompt statuses
   pending        Ready for the next session to consume.
                  \`runlist prompts use <file>\` prints body + archives atomically.
                  \`runlist prompts next\` does the same for the oldest pending.
+                 Outside an agent session both only print, and the
+                 prompt stays pending.
 
   archived       Consumed prompt; body preserved in the archive directory,
                  which is the only directory a prompt ever moves into.
@@ -1284,6 +1287,11 @@ Prompts are documents with \`type: prompt\`, typically saved under
 docs/prompts/. They seed future Claude sessions; consuming a prompt
 prints its body to stdout and atomically archives it (one-shot).
 
+Only an agent session consumes (Claude Code, Codex, OpenCode, or a shell
+with RUNLIST_SESSION_ID set). In a plain terminal \`use\`, \`resume\` and
+\`next\` print the body and a closing line naming the command the session
+runs to consume it; the prompt stays pending and its plan unclaimed.
+
 \`runlist prompt\` (singular) is an alias for \`runlist prompts\` — every
 subcommand below works under either spelling.
 
@@ -1330,10 +1338,11 @@ Examples:
   runlist prompts list --status claimed   # already-consumed prompts
   runlist prompts --json                 # JSON output
 
-  claude "$(runlist prompts next)"       # consume oldest pending + run claude
-  claude "$(runlist prompts use resume-foo)"           # by slug
-  claude "$(runlist prompts use docs/prompts/foo.md)"  # by path
-  claude "$(runlist prompts resume resume-foo)"        # \`resume\` is an alias for \`use\`
+  runlist prompts use resume-foo        # in a session: consume by slug
+  runlist prompts use docs/prompts/foo.md  # by path
+  runlist prompts resume resume-foo     # \`resume\` is an alias for \`use\`
+  claude "$(runlist prompts next)"       # from a terminal: start claude on the oldest
+                                       # pending; the session consumes it itself
   runlist prompt list                    # singular alias for \`runlist prompts list\`
 
   runlist prompts show resume-foo        # peek without consuming (triage)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.98.2",
+  "version": "0.99.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.98.2",
+  "version": "0.99.0",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

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

@@ -20,7 +20,7 @@ Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`.
 - **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`. Add `--parent resume-<session-name>` to link the child beneath its parent in `rl prompts`; the parent may be saved later. 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.
 - **Draft outlines:** `runlist baton --template` prints the resume outline. The desktop Templates editor saves resume/subagent outlines in `runlist.templates.json`; repository baton instructions still apply.
 - **Child draft:** `runlist baton --subagent --template --parent resume-<name>` prints the saved child outline (built-in: Task, State, Next, Evidence and Boundaries). Fill the draft; its `parent_prompt` travels on save. A launcher can pass `RUNLIST_PARENT_PROMPT` into the child environment instead. Keep full records at durable repo-relative paths with commits and checked results; temporary scratch paths are supplementary. Completed work is a result for the parent to record, not another restart. Repair old links without replacing text: `runlist prompts link <child...> --parent resume-<name>`. Showing or consuming a parent surfaces its pending children without consuming them.
-- 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`.
+- Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. Only an agent session consumes; a plain terminal gets the body plus the `runlist prompts use <path>` line, and the prompt stays pending. A prompt that ends with that line is still pending: run the command first. 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.
 - Record a decision with `runlist new decision <plan> --question "…" @<record-file>`; configured registers may also require `--answers`.

package/src/git-commit-support.mjs

@@ -1,11 +1,12 @@
 // Keep the service and worker on the same terminal-qualified matrix.
+// macOS evidence: Homebrew Git 2.56.0 passed the guarded-commit suite on ARM64.
 // Linux evidence: Debian 13 ARM64 / Git 2.47.3, pinned Node 24.21.0.
 export function commitPlatformQualified(platform=process.platform,arch=process.arch){
  return arch==='arm64'&&(platform==='darwin'||platform==='linux');
 }
 export function commitVersionQualified(version,platform=process.platform,arch=process.arch){
  if(!commitPlatformQualified(platform,arch))return false;
- return platform==='darwin'?/^git version 2\.(54|55)\.0(?: |$)/.test(version):version==='git version 2.47.3';
+ return platform==='darwin'?/^git version 2\.(54|55|56)\.0(?: |$)/.test(version):version==='git version 2.47.3';
 }
 export function localCommitSupport(version,platform=process.platform,arch=process.arch){
  const available=commitVersionQualified(version,platform,arch);

package/src/prompts.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath, resolveRefPath, isArchivedPath } from './util.mjs';
+import { agentSessionSource, asString, toRepoPath, die, resolveDocPath, resolveRefPath, isArchivedPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
 import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive } from './lifecycle.mjs';
@@ -372,6 +372,13 @@ export async function consumePrompt(filePath, config, opts) {
   }
   const family = childHandoffs(repoPath, config);
 
+  // Only an agent session consumes. A plain terminal (`claude "$(runlist use)"`,
+  // or someone looking) gets the body and the command the session runs, so a
+  // session that never starts takes nothing and claims no plan.
+  if (!dryRun && !agentSessionSource(opts.env ?? process.env)) {
+    return printUnconsumedPrompt(body + family.notice, repoPath, status);
+  }
+
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
   let claimSkipReason = null;
@@ -401,8 +408,8 @@ export async function consumePrompt(filePath, config, opts) {
 
   // Archive BEFORE emitting the body. If runArchive throws (git mv failure,
   // hook crash, anything), the body must not have already gone to stdout —
-  // otherwise `claude "$(runlist prompts next)"` consumes the prompt without it
-  // ever being archived, and the next session sees the same prompt as pending.
+  // otherwise the session reads a prompt that was never archived, and the next
+  // session sees the same prompt as pending.
   const archiveResult = runArchive([filePath], config, {
     noIndex,
     showFiles,
@@ -476,6 +483,24 @@ export async function consumePrompt(filePath, config, opts) {
   };
 }
 
+export function consumeInstruction(repoPath) {
+  return `This prompt is still pending: runlist consumes a prompt only inside an agent session. The session that works on it runs \`runlist prompts use ${repoPath}\` first.`;
+}
+
+async function printUnconsumedPrompt(body, repoPath, status) {
+  const content = `${body}${body.endsWith('\n') ? '' : '\n'}\n${consumeInstruction(repoPath)}\n`;
+  await new Promise((resolve, reject) => process.stdout.write(content, err => err ? reject(err) : resolve()));
+  return {
+    operation: 'print',
+    status: { from: status ?? null, to: status ?? null, changed: false },
+    repositoryFiles: [],
+    sessionFiles: [],
+    generatedFiles: [],
+    deferredGeneratedFiles: [],
+    claim: null,
+  };
+}
+
 function linkedPlanRepoPath(planRef, promptPath, config) {
   const abs = resolveRefPath(planRef, path.dirname(promptPath), config.repoRoot);
   return abs && existsSync(abs) ? toRepoPath(abs, config.repoRoot) : null;

package/src/util.mjs

@@ -52,6 +52,17 @@ export function hostSessionSource(env = process.env) {
   return null;
 }
 
+// The agent session runlist runs inside, or null in a plain terminal. A
+// terminal id names a window, not an agent, so it does not count: consuming a
+// prompt there would archive it with no session to read it.
+export function agentSessionSource(env = process.env) {
+  const source = hostSessionSource(env);
+  return source && source.scope !== 'terminal' ? source : null;
+}
+
+// Every variable that can name a session, for a caller that must clear them all.
+export const SESSION_ID_VARIABLES = SESSION_ID_SOURCES.map(source => source.variable);
+
 // The session id the environment names, or null when it names none.
 export function hostSessionId(env = process.env) {
   return hostSessionSource(env)?.id ?? null;