@miroshnik/elves 2026.1018.1 → 2026.1018.2

package/AGENTS.md

@@ -2,9 +2,8 @@
 
 ## This file and skills
 
-The Elves canon for any agent (Claude Code, Codex, Gemini CLI, Cursor,
-Copilot, OpenCode, Amp). It lives in **miroshnik/elves** with the skills
-(`skills/*`) and references (`docs/`, next to this file), installed
+The Elves canon for any agent. It lives in **miroshnik/elves** with the
+skills (`skills/*`) and references (`docs/`, next to this file), installed
 onto the machine — README, "Installation". A rule or skill change from
 another project's session is a task in Elves (project #6) without that
 project's names, for a separate session; I don't edit an Elves clone from
@@ -89,8 +88,7 @@ done. The session can be closed.` · `All done, but there are questions: …` ·
 
 - Tasks live in the repository's **GitHub Issues**, not in local lists, TODO
   files or the agent's task list; no repository — ask where. The `github`
-  skill runs them (`task new`, `show`, `answer`, `status`, `close`, `drop`,
-  `pr labels`), not `gh issue view`/`edit`; how tasks, the project and
+  skill runs them, not `gh issue view`/`edit`; how tasks, the project and
   milestones are organized — its `reference.md`.
 - **Types:** Task (one PR), Bug, Epic (a personal account — the `epic`
   label). **Decision labels** — the decision's name, kind by color: a task
@@ -121,11 +119,13 @@ done. The session can be closed.` · `All done, but there are questions: …` ·
   question «run the dispatcher on epic #M?», without In progress.
 - **A dispatcher** — "do all tasks of epic #M", "fix all High bugs", a "yes"
   — any session, its task stays; one started for it — in the project folder,
-  not a worktree: executors start from `main`. `github task queue` — ready
-  ones with executors' prompts; an executor — a background subagent in its
-  worktree or a cloud session: at most 3 subagents and 5 cloud sessions at
-  once, the owner's number replaces either; its question — to the owner,
-  the answer into the issue and back; failed — a task comment, no restart.
+  not a worktree: executors start from `main`. `github task queue` prints
+  executors' prompts; an executor — a background subagent in its worktree or
+  a cloud session: at most 3 subagents and 5 cloud sessions at once, the
+  owner's number replaces either; failed — a task comment, no restart; an
+  executor session whose task closed — the dispatcher archives it in an auto
+  project, not one still working in the background or awaiting the owner's
+  answer; outside auto the owner closes it.
 - **The session is named `#<number> <task title>`** (without a task — by
   meaning, no number) as soon as the task is clear (no tool — ask the user):
   `est` links the session to the task by it.

package/README.md

@@ -216,7 +216,7 @@ The machine's copy and a project's package version follow the flow **by releases
 <details>
 <summary><b>The package in a project — the harness and the scripts at the project's version</b></summary>
 
-With `@miroshnik/elves` in a project's `devDependencies`, `bun install` brings the flow at the project's version — for CI, colleagues and a cloud session too (npm works there, `github:` gives 403). Tests import `@miroshnik/elves/spec/harness`, `@miroshnik/elves/spec/architecture`, `@miroshnik/elves/spec/eslint-config` and `@miroshnik/elves/github`: Bun and the type checker take the TypeScript source, any runner on Node (Jest, Playwright, `node:test`, the project's `eslint.config.js`) — the build. The skills' scripts run from `node_modules/.bin` with the same arguments as the scripts themselves, under `bun --no-env-file` — in `package.json` and CI alike: `bun` reads the TypeScript bin `elves` itself, past its shebang, and without the flag it would get the project's env files (`.env.local` with production keys) and pass their keys on to `gh`, `git` and the checked command. On Yarn 2+ — `bunx @miroshnik/elves@"$(jq -r '.devDependencies["@miroshnik/elves"]' package.json)" <script>`, the form `install` writes there: Yarn 2+ runs a `.ts` bin by Node with any `nodeLinker`, and PnP has no `node_modules`.
+With `@miroshnik/elves` in a project's `devDependencies`, `bun install` brings the flow at the project's version — for CI, colleagues and a cloud session too (npm works there, `github:` gives 403). Tests import `@miroshnik/elves/spec/harness`, `@miroshnik/elves/spec/architecture`, `@miroshnik/elves/spec/eslint-config` and `@miroshnik/elves/github`: Bun and the type checker take the TypeScript source, any runner on Node (Jest, Playwright, `node:test`, the project's `eslint.config.js`) — the build; the knip reporter `@miroshnik/elves/spec/knip-hints` is CommonJS as is, its `file` — the path for `knip --reporter`. The skills' scripts run from `node_modules/.bin` with the same arguments as the scripts themselves, under `bun --no-env-file` — in `package.json` and CI alike: `bun` reads the TypeScript bin `elves` itself, past its shebang, and without the flag it would get the project's env files (`.env.local` with production keys) and pass their keys on to `gh`, `git` and the checked command. On Yarn 2+ — `bunx @miroshnik/elves@"$(jq -r '.devDependencies["@miroshnik/elves"]' package.json)" <script>`, the form `install` writes there: Yarn 2+ runs a `.ts` bin by Node with any `nodeLinker`, and PnP has no `node_modules`.
 
 ```bash
 bun --no-env-file node_modules/.bin/elves spec-doc …
@@ -227,9 +227,17 @@ bun --no-env-file node_modules/.bin/elves spec-shard …
 bun --no-env-file node_modules/.bin/elves spec-claims …
 bun --no-env-file node_modules/.bin/elves spec-break …
 bun --no-env-file node_modules/.bin/elves spec-exceptions …
+bun --no-env-file node_modules/.bin/elves task-env up …
+bun --no-env-file node_modules/.bin/elves task-env e2e …
+bun --no-env-file node_modules/.bin/elves task-env down …
+bun --no-env-file node_modules/.bin/elves task-env prune
+bun --no-env-file node_modules/.bin/elves task-env check …
+bun --no-env-file node_modules/.bin/elves task-env proxy up
+bun --no-env-file node_modules/.bin/elves task-env proxy down
+bun --no-env-file node_modules/.bin/elves task-env proxy status
 ```
 
-The machine queue — `elves slot --for <PID>` of the shim `.agents/slot.sh`: it only prints the queue variables, the command runs in the script's own shell. A GitHub Actions step doesn't see `node_modules/.bin`, and `bunx elves` without the package in `node_modules` would fetch someone else's `elves` from npm; a job that doesn't install the project's dependencies — `bunx @miroshnik/elves@<version> <script>` (the `spec` skill's `ci.md`).
+The project's own scripts and tests (the stack before the dev server, the e2e wrapper) bring the task's stack up with `elves task-env up` — the `task-env` skill at the project's version. The machine queue — `elves slot --for <PID>` of the shim `.agents/slot.sh`: it only prints the queue variables, the command runs in the script's own shell. A GitHub Actions step doesn't see `node_modules/.bin`, and `bunx elves` without the package in `node_modules` would fetch someone else's `elves` from npm; a job that doesn't install the project's dependencies — `bunx @miroshnik/elves@<version> <script>` (the `spec` skill's `ci.md`).
 
 </details>
 

package/bin/elves.ts

@@ -15,6 +15,7 @@
  *   bun <Elves checkout>/bin/elves.ts pack <tag>       — CI on the release tag: the npm package @miroshnik/elves
  *   bun --no-env-file node_modules/.bin/elves spec-doc … — a project's package: the skills' scripts at its version
  *   elves slot --for <PID>                             — the machine queue's shim .agents/slot.sh in a project
+ *   bun --no-env-file node_modules/.bin/elves task-env up — a project's scripts and tests: the task's stack, task-env
  *
  * The shebang goes through `sh`: the second line — `exec bun --no-env-file` for sh, a string and a comment for TypeScript
  * — starts Bun without the project's env files however the bin is called (`elves`, `node_modules/.bin/elves`, a
@@ -32,8 +33,9 @@
  * settings, #610); updating the project is bumping the package version — a few lines in the branch of the current task.
  * A project with a copy of an earlier release loads the canon twice until it moves — the hook names it (`twiceLines`);
  * `install` and `update` move it to a thin one: the copy, its symlinks and `.gitignore` exceptions go (`removeCopy`),
- * the imports and CI paths into the copy lead to the package (`rewriteCopyRefs`), the rest that names `.agents` is
- * listed (`copyLeftovers`).
+ * the imports, scripts and CI paths into the copy lead to the package (`rewriteCopyRefs`), the rest that names `.agents`
+ * is listed (`copyLeftovers`), and `check` names a line into a file of the copy that update doesn't rewrite with `!`
+ * (`copyRefs`, #620).
  * `.agents/elves.json` — on the machine the Elves SHA it was installed from, the list of installed skills (by it a
  * reinstall removes skills Elves no longer has and leaves others' alone), for a machine with `--link` — the clone path;
  * in a project — only `auto`: whether the agent runs a task entirely by itself — answers to questions by
@@ -208,8 +210,9 @@ on the machine and the cloud session's SessionStart hook in .claude/settings.jso
 it exits at once; the package.json checks (lint, typecheck, test, test:*) go through the shim, the skills' scripts —
 ${PACKAGE_RUN} <script>, without the project's env files; on Yarn 2+, which runs the .ts bin by Node, both go through
 the package of the project's version — ${PACKAGE_BUNX} <script>. A project with a copy of the flow
-of an earlier release moves to a thin one: the copy, its symlinks and .gitignore exceptions go, imports and CI paths
-into the copy lead to the package, what else names .agents is listed.
+of an earlier release moves to a thin one: the copy, its symlinks and .gitignore exceptions go, imports into the copy
+(the knip reporter — ${PACKAGE}/spec/knip-hints) and its scripts run by bun or node in package.json, shell scripts,
+command strings and CI (task-env too) lead to the package, what else names .agents is listed.
 In a terminal asks whether the agent does tasks entirely by itself — answers by recommendation, commit, push,
 fixing CI, merge on green checks (auto in .agents/elves.json, default — no); without a terminal — the --auto or
 --no-auto flag, without the flag the previous answer stays; with auto prints the Claude Code permission rule for the
@@ -238,7 +241,8 @@ package — by restarting from the latest release's package), a --link clone —
 mode (auto) and the language, holds the compose file to the task isolation rules (❌ per violation, ○ — not checked: no
 docker compose; the task-env skill), names a test that runs standards and architecture again next to test:spec (○, the
 ready test without them) and warns (!) if a script in slot calls turbo and turbo.json doesn't pass the queue variables
-to tasks (the exit code stays the same); a thin project behind — update in this session's task (the package version in
+to tasks or a line leads into a file of the flow copy that update doesn't rewrite — the file, the line number and its
+text (the exit code stays the same); a thin project behind — update in this session's task (the package version in
 package.json and the lockfile), a project with a copy of the flow — the move to a thin project in a task of its own: the
 task new command of the github skill, one task per project. For the machine names the task-env proxy of *.localhost
 addresses — running, not running or running
@@ -258,12 +262,14 @@ Examples:
 Brings it up to date: a --link clone — git pull --ff-only, the machine's copy — install of the latest release: the
 canon, the skills and the hook; a project — install of the latest release: ${PACKAGE} in package.json and the
 lockfile, a few lines in the branch of the current task; a project with a copy of the flow moves to a thin one (install
---help); from the npm package — by restarting from the latest release's package. The project's mode and language are
-kept; an install of a previous version without a language gets ru: before the field the flow worked in Russian. In a
-project install and update un-ignore flow files from .gitignore patterns with exceptions at its end and wrap the
-package.json checks (lint, typecheck, test, test:*) in the machine queue slot; prints what changed: every release after
-the installed one, newest first, with the list of changes of its GitHub Release (a --link clone — the flow commits it
-pulled), and the git add of what changed. An install from before the rename to Elves — the ai-dev names
+--help), by hand after it — a check of the project that knows the queue wrapper by the copy's path (. .agents/slot.sh
+now), AI_DEV_SLOT* in the project's code → ELVES_SLOT*, formatting the shortened imports, git add -A before the first
+run of the checks, the ! lines of check; from the npm package — by restarting from the latest release's package. The
+project's mode and language are kept; an install of a previous version without a language gets ru: before the field
+the flow worked in Russian. In a project install and update un-ignore flow files from .gitignore patterns with
+exceptions at its end and wrap the package.json checks (lint, typecheck, test, test:*) in the machine queue slot;
+prints what changed: every release after the installed one, newest first, with the list of changes of its GitHub
+Release (a --link clone — the flow commits it pulled), and the git add of what changed. An install from before the rename to Elves — the ai-dev names
 (.agents/ai-dev.json, .agents/ai-dev/, .claude/rules/ai-dev*.md, the blocks in AGENTS.md and .gitignore,
 ~/.config/ai-dev) move to the new ones with the same contents.
 
@@ -296,22 +302,41 @@ Examples:
  * arguments, in this process; the project's paths (`.agents/elves.json`, `tests/`, the reports) come from the current
  * directory and its git root, as with `bun <copy>/scripts/<script>.ts`. No release launcher (`toRelease`): the version
  * is the project's. Help — the script's own `HELP` under the elves name; `--help` counts where the script reads it: a
- * spec script — before `--`, slot — only as the first argument (the rest is its command). A script module runs its
- * `main` itself only as the entry point (`import.meta.main`).
+ * spec script and task-env — before `--`, slot — only as the first argument (the rest is its command). A script module
+ * runs its `main` itself only as the entry point (`import.meta.main`). task-env — so that a project's scripts and tests
+ * (bringing the stack up before the dev server, the e2e wrapper, the compose isolation test) call it at the project's
+ * version without a path into a skill directory, which breaks when the package isn't hoisted to the root
+ * `node_modules` (#620).
  */
 const SCRIPTS: Record<string, { file: string; helpFirst?: boolean }> = {
   ...Object.fromEntries(["spec-doc", "spec-diff", "spec-publish", "spec-run", "spec-shard", "spec-claims", "spec-break", "spec-exceptions"].map((name) => [name, { file: `skills/spec/scripts/${name}.ts` }])),
   slot: { file: "skills/slot/scripts/slot.ts", helpFirst: true },
+  "task-env": { file: "skills/task-env/scripts/task-env.ts" },
 };
 
-/** A script of SCRIPTS: its help and its entry point. */
+/**
+ * A script of SCRIPTS: its help and its entry point. A script with commands (task-env) — its help is a table by
+ * command and an overview of them all.
+ */
 interface Script {
-  HELP: string;
+  HELP: string | Record<string, string>;
+  OVERVIEW?: string;
   main: (argv: string[]) => number | Promise<number>;
 }
 
 const loadScript = (cmd: string): Promise<Script> => import(path.join(SRC, SCRIPTS[cmd]!.file));
 
+/** A script's help the arguments ask for: the text; with commands — of the command they start with, otherwise the overview. */
+function helpText(s: Script, args: string[]): string {
+  if (typeof s.HELP === "string") return s.HELP;
+  const table = s.HELP;
+  const command = Object.keys(table).find((c) => `${args.join(" ")} `.startsWith(`${c} `));
+  return command ? table[command]! : (s.OVERVIEW ?? "");
+}
+
+/** The synopses of a script for the `elves --help` overview: the first paragraph of its help, of each command's for a table. */
+const synopses = (s: Script) => (typeof s.HELP === "string" ? [s.HELP] : Object.values(s.HELP)).map((h) => h.split("\n\n")[0]!);
+
 /**
  * The package's script in the current project — the form of its package.json: on Yarn 2+ through bunx (`packageRun`).
  * The root — by `.git` up from the current directory, without git: help runs no external commands
@@ -325,25 +350,26 @@ const projectRun = () => packageRun(packageManager(locale.projectRoot(process.cw
  * the form of package.json and CI and the project's version, while bare `elves` in the agent's shell is the machine's
  * global package, if it's on PATH at all (tests/standards/no-env-file).
  */
-const scriptHelp = async (cmd: string, run = projectRun()) => (await loadScript(cmd)).HELP.replace(new RegExp(`^( *)${cmd}(?= |$)`, "gm"), `$1${run} ${cmd}`).trimEnd();
+const underElves = (cmd: string, text: string, run = projectRun()) => text.replace(new RegExp(`^( *)${cmd}(?= |$)`, "gm"), `$1${run} ${cmd}`).trimEnd();
 
 /** `elves <script> …`: the script's help or its `main` with the arguments; the exit code is the script's. */
 async function runScript(cmd: string, args: string[]): Promise<number> {
   const options = SCRIPTS[cmd]!.helpFirst ? args.slice(0, 1) : args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
-  if (options.some((a) => a === "--help" || a === "-h")) return note(await scriptHelp(cmd)), 0;
-  return (await loadScript(cmd)).main(args);
+  const script = await loadScript(cmd);
+  if (options.some((a) => a === "--help" || a === "-h")) return note(underElves(cmd, helpText(script, options))), 0;
+  return script.main(args);
 }
 
 /** `elves --help`: the synopsis of each command, the scripts' too, and how to run it. */
 async function overview() {
   const synopsis = (h: string) => h.split("\n\n")[0]!.replace(/^/gm, "  ");
   const run = projectRun();
-  const scripts = await Promise.all(Object.keys(SCRIPTS).map((cmd) => scriptHelp(cmd, run)));
+  const scripts = await Promise.all(Object.keys(SCRIPTS).map(async (cmd) => synopses(await loadScript(cmd)).map((h) => underElves(cmd, h, run))));
   return [
     "elves — the rules and skills of the Elves flow: install, check, update, release, pack; skill scripts at a project's version",
     "",
     ...Object.values(HELP).map(synopsis),
-    ...scripts.map(synopsis),
+    ...scripts.flat().map(synopsis),
     "",
     "elves <command> --help — the command's details and examples",
     `Run: ${RUN} <command>; in a project with ${PACKAGE} in devDependencies — ${run} <command>`,
@@ -842,22 +868,28 @@ function slotShim(root: string) {
 }
 
 /**
- * A skill script the flow copy runs — `bun [--no-env-file] .agents/skills/<skill>/scripts/<script>.ts` of SCRIPTS — and
- * the knip reporter of the copy (`knip --reporter …/knip-hints.cjs`, the harness's `report`): the package has them,
- * the copy is gone. The script and its arguments are the same (SCRIPTS).
+ * A skill script the flow copy runs — `bun|node [--<flag>]… .agents/skills/<skill>/scripts/<script>.ts` of SCRIPTS, the
+ * forms projects used (`bun --no-env-file`, `node --experimental-strip-types`, `./` before the path, #620) — and the knip
+ * reporter of the copy (`knip --reporter …/knip-hints.cjs`, the harness's `report`): the package has them, the copy is
+ * gone. The script and its arguments are the same (SCRIPTS).
  */
-const COPY_SCRIPT = /\bbun(?: --no-env-file)? (?:\.\/)?\.agents\/skills\/(?:spec|slot)\/scripts\/([\w-]+)\.ts\b/g;
+const COPY_SCRIPT = /\b(?:bun|node)(?: --[\w-]+)* (?:\.\/)?\.agents\/skills\/([\w-]+)\/scripts\/([\w-]+)\.ts\b/g;
 const COPY_KNIP_HINTS = /(?:\.\/)?\.agents\/skills\/spec\/scripts\/knip-hints\.cjs\b/g;
-/** The knip reporter in the project's package: `exports` of package.json don't have it, the file does. */
+/**
+ * The knip reporter in the project's package for a command (`knip --reporter <file>`); a module takes its path from the
+ * export — `file` of `@miroshnik/elves/spec/knip-hints` (`COPY_IMPORT`).
+ */
 const PACKAGE_KNIP_HINTS = `node_modules/${PACKAGE}/skills/spec/scripts/knip-hints.cjs`;
 
 /**
  * A command that ran the copy's scripts — through the package: `<run> <script>`, `PACKAGE_RUN` by default; on Yarn 2+
  * and in a CI job without the project's dependencies — `PACKAGE_BUNX` (`packageRun`, `ciFromCopy`). A script that isn't
- * the package's stays — `copyLeftovers` names it.
+ * the package's stays — `copyLeftovers` names it, `check` — `copyRefs`.
  */
 function fromCopy(text: string, run = PACKAGE_RUN) {
-  return text.replace(COPY_SCRIPT, (all, name: string) => (Object.hasOwn(SCRIPTS, name) ? `${run} ${name}` : all)).replace(COPY_KNIP_HINTS, PACKAGE_KNIP_HINTS);
+  return text
+    .replace(COPY_SCRIPT, (all, skill: string, name: string) => (Object.hasOwn(SCRIPTS, name) && SCRIPTS[name]!.file === `skills/${skill}/scripts/${name}.ts` ? `${run} ${name}` : all))
+    .replace(COPY_KNIP_HINTS, PACKAGE_KNIP_HINTS);
 }
 
 /**
@@ -891,9 +923,7 @@ function packageScripts(root: string) {
   let hidden = false;
   for (const [name, cmd] of Object.entries(scripts)) {
     if (typeof cmd !== "string") continue;
-    const inner = slotted(name) ? unslot(cmd) : cmd;
-    const own = fromCopy(inner, run);
-    const want = slotted(name) ? wrap(own) : own;
+    const { inner, own, want } = scriptAfter(name, cmd, yarn);
     if (cmd === want) continue;
     scripts[name] = want;
     if (own !== inner) copy.push(name);
@@ -918,6 +948,16 @@ function packageScripts(root: string) {
   if (copy.length) note(`package.json — the flow copy's scripts through the package (${run} <script>): ${copy.join(", ")}`);
 }
 
+/**
+ * A package.json script as the install leaves it (`packageScripts`): `inner` — its own command without a slot wrapper,
+ * `own` — with the copy's scripts through the package, `want` — a check wrapped in the machine queue.
+ */
+function scriptAfter(name: string, cmd: string, yarn: boolean) {
+  const inner = slotted(name) ? unslot(cmd) : cmd;
+  const own = fromCopy(inner, packageRun(yarn));
+  return { inner, own, want: slotted(name) ? slotWrap(yarn)(own) : own };
+}
+
 /**
  * Queue variables a command in a slot needs: the runner's share of cores and "already in a slot" for a nested script
  * in slot.
@@ -1054,6 +1094,18 @@ function projectHook(root: string, clone: boolean) {
 function agentsBlock(root: string) {
   const file = path.join(root, "AGENTS.md");
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const out = agentsWith(text);
+  if (out !== text) {
+    const former = text.includes(FORMER.begin) ? { note: `the block under the flow's former name (${FORMER.begin.slice(5)}) — update replaces it` } : {};
+    if (dry) return change(text ? "~" : "+", file, former);
+    writeFileSync(file, out);
+    touch("AGENTS.md");
+  }
+  note(`AGENTS.md — a block linking to ~/${CANON}/AGENTS.md on the machine`);
+}
+
+/** The project's AGENTS.md text with the block in place: the block of an earlier install or under the former name replaced, a second one gone. */
+function agentsWith(text: string) {
   let out = text;
   let placed = false;
   for (const [begin, end] of [
@@ -1067,14 +1119,7 @@ function agentsBlock(root: string) {
     out = placed ? out.slice(0, b) + out.slice(e + end.length).replace(/^\n+/, "") : out.slice(0, b) + BLOCK + out.slice(e + end.length);
     placed = true;
   }
-  if (!placed) out = text ? `${BLOCK}\n\n${text}` : `${BLOCK}\n`;
-  if (out !== text) {
-    const former = text.includes(FORMER.begin) ? { note: `the block under the flow's former name (${FORMER.begin.slice(5)}) — update replaces it` } : {};
-    if (dry) return change(text ? "~" : "+", file, former);
-    writeFileSync(file, out);
-    touch("AGENTS.md");
-  }
-  note(`AGENTS.md — a block linking to ~/${CANON}/AGENTS.md on the machine`);
+  return placed ? out : text ? `${BLOCK}\n\n${text}` : `${BLOCK}\n`;
 }
 
 const GI_BEGIN = "# elves:begin";
@@ -1499,11 +1544,31 @@ function gitGrep(root: string, args: string[]): string[] {
 const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
 /** A workflow or an action of GitHub Actions: the copy's scripts go there by path. */
 const CI_FILE = /^\.github\/.*\.ya?ml$/;
-/** An import of a copy's module the package exports (`exports` of package.json): the harness, the model, the ESLint fragment, github. */
-const COPY_IMPORT = /(["'`])(?:\.{1,2}\/)*\.agents\/skills\/(spec\/scripts\/(?:harness|architecture|eslint-config)|github\/scripts\/github)(?:\.[cm]?[jt]s)?\1/g;
+/** A shell script of the project: the copy's scripts go there by path (#620) — bringing the stack up, the e2e wrapper. */
+const SHELL_FILE = /\.(?:sh|bash|zsh)$/;
+/**
+ * An import of a copy's module the package exports (`exports` of package.json): the harness, the model, the ESLint
+ * fragment, the knip reporter (its `file` — the path for `knip --reporter`, #620), github.
+ */
+const COPY_IMPORT = /(["'`])(?:\.{1,2}\/)*\.agents\/skills\/(spec\/scripts\/(?:harness|architecture|eslint-config|knip-hints)|github\/scripts\/github)(?:\.[cm]?[jt]s)?\1/g;
 /** The package's export of a copy's module: spec/scripts/harness → @miroshnik/elves/spec/harness, github/scripts/github → @miroshnik/elves/github. */
 const packageImport = (mod: string) => `${PACKAGE}/${mod.startsWith("spec/") ? mod.replace("/scripts/", "/") : "github"}`;
 
+/**
+ * A project's file with what leads into the copy rewritten, by the file's kind: a workflow — `ciFromCopy` (its jobs
+ * whether dependencies are installed is unknown — `unknown`); a shell script — the copy's scripts through the package,
+ * the form of package.json; a source file — imports of the copy's modules to the package's exports and the copy's
+ * scripts in its command strings (on Yarn 2+ only the imports: the bunx form has quotes a string literal doesn't
+ * take). Another kind — null: the install doesn't rewrite it.
+ */
+function copyRewrite(rel: string, text: string, berry: boolean): { out: string; unknown: string[] } | null {
+  if (CI_FILE.test(rel)) return ciFromCopy(text, berry);
+  if (SHELL_FILE.test(rel)) return { out: fromCopy(text, packageRun(berry)), unknown: [] };
+  if (!SOURCE_FILE.test(rel)) return null;
+  const imports = text.replace(COPY_IMPORT, (_, q: string, mod: string) => `${q}${packageImport(mod)}${q}`);
+  return { out: berry ? imports : fromCopy(imports), unknown: [] };
+}
+
 /**
  * A step that installs the project's dependencies: `bun`, `npm`, `pnpm` or `yarn` with `install`, `ci`, `i`, a bare
  * `yarn`; a global install (`-g`, `--global`) brings a tool, not them.
@@ -1581,24 +1646,24 @@ function ciFromCopy(text: string, berry: boolean) {
 }
 
 /**
- * Files of the project that lead into the copy (#558): imports of the copy's modules in tests and configs — to the
- * package's exports (`@miroshnik/elves/spec/harness` …), its scripts and the knip reporter in GitHub Actions — through
- * the package by the job (`ciFromCopy`), a job whether dependencies are installed is unknown — a `!` line;
- * package.json — `packageScripts`. Only tracked files that name `.agents/skills/`.
+ * Files of the project that lead into the copy (#558, #620): imports of the copy's modules in tests and configs — to the
+ * package's exports (`@miroshnik/elves/spec/harness`, `…/spec/knip-hints` …), its scripts in shell scripts and command
+ * strings of source files — through the package, in GitHub Actions — through the package by the job (`ciFromCopy`), a
+ * job whether dependencies are installed is unknown — a `!` line; package.json — `packageScripts` (`copyRewrite`). Only
+ * tracked files that name `.agents/skills/`; what is left — `copyLeftovers`, in `check` — `copyRefs`.
  */
 function rewriteCopyRefs(root: string) {
   const done: string[] = [];
   const berry = packageManager(root).berry;
   for (const rel of gitGrep(root, ["-l", "-F", "-e", ".agents/skills/"])) {
-    const ci = CI_FILE.test(rel);
-    if (!ci && !SOURCE_FILE.test(rel)) continue;
     const file = path.join(root, rel);
     const text = readFileSync(file, "utf8");
-    const { out, unknown } = ci ? ciFromCopy(text, berry) : { out: text.replace(COPY_IMPORT, (_, q: string, mod: string) => `${q}${packageImport(mod)}${q}`), unknown: [] };
-    if (out === text) continue;
+    const rewritten = copyRewrite(rel, text, berry);
+    if (!rewritten || rewritten.out === text) continue;
+    const { out, unknown } = rewritten;
     if (dry) {
       const scripts = berry ? "the package through bunx (Yarn 2+)" : "the package: node_modules/.bin/elves, a job without dependencies — bunx";
-      change("~", file, { note: ci ? `the flow copy's scripts → ${scripts}` : `imports of the flow copy → ${PACKAGE}` });
+      change("~", file, { note: CI_FILE.test(rel) ? `the flow copy's scripts → ${scripts}` : SHELL_FILE.test(rel) ? `the flow copy's scripts → ${PACKAGE}` : `imports and scripts of the flow copy → ${PACKAGE}` });
       continue;
     }
     writeFileSync(file, out);
@@ -1630,6 +1695,50 @@ function copyLeftovers(root: string) {
   if (lines.length) note([`Still naming .agents — the flow copy is gone: exceptions for it in linters, formatters and configs aren't needed anymore, a path into it leads to ${PACKAGE} or a skill on the machine; fix by hand:`, ...capped(lines)].join("\n"));
 }
 
+/**
+ * A path into a file of the flow copy: its canon (CANON, under the former name too) and the flow's skills
+ * (`.agents/skills/<skill>/`). A project's own skill, the manifest and the shim are the thin project's own, `~/.agents`
+ * and `$HOME/.agents` — the machine's.
+ */
+const copyRef = () => {
+  const dirs = [CANON, FORMER.canon, ...sourceSkills(SRC).map((s) => `.agents/skills/${s}`)].map(locale.escapeRe).join("|");
+  return new RegExp(String.raw`(?<![\w~}-]|~\/|HOME\/|HOME}\/)(?:${dirs})\/`);
+};
+
+/**
+ * `check` (#620): a line of the project that leads into a file of the flow copy after the install — a form `update`
+ * doesn't rewrite (a path in an argument array, an import of the copy's canon) — a `!` line with the file, the line
+ * number and its text: without it `check` says "up to date" after the move, and the project's checks fail on a file
+ * that is gone. The line is taken as the install leaves it — what `update` rewrites isn't named; `.gitignore` doesn't
+ * count, its Elves block is the install's. At most MAX_LINES lines, the rest — a count.
+ */
+function copyRefs(root: string) {
+  const ref = copyRef();
+  const berry = packageManager(root).berry;
+  const found: string[][] = [];
+  for (const rel of gitGrep(root, ["-l", "-F", "-e", ".agents/"])) {
+    if (rel === ".gitignore") continue;
+    const text = readFileSync(path.join(root, rel), "utf8");
+    const after = rel === "package.json" ? scriptsAfterText(text, yarnShell(root)) : rel === "AGENTS.md" ? agentsWith(text) : (copyRewrite(rel, text, berry)?.out ?? text);
+    after.split("\n").forEach((line, i) => ref.test(line) && found.push([rel, `${i + 1}`, line.trim().slice(0, 120)]));
+  }
+  const fix = `a path into the flow copy update doesn't rewrite — a skill's script: ${packageRun(berry)} <script>, a module: ${PACKAGE}/<export>, the canon and skills: ~/.agents; fix by hand`;
+  for (const [rel, n, line] of found.slice(0, MAX_LINES)) change("!", path.join(root, `${rel}:${n}`), { note: `${line} — ${fix}` });
+  if (found.length > MAX_LINES) change("!", path.join(root, "…"), { note: `and ${found.length - MAX_LINES} more lines into the flow copy` });
+}
+
+/** package.json with its scripts as the install leaves them (`scriptAfter`); not JSON — as is. */
+function scriptsAfterText(text: string, yarn: boolean) {
+  try {
+    const pkg = JSON.parse(text) as { scripts?: Record<string, unknown> };
+    const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    for (const [name, cmd] of Object.entries(scripts)) if (typeof cmd === "string") scripts[name] = scriptAfter(name, cmd, yarn).want;
+    return JSON.stringify(pkg, null, /^([ \t]+)"/m.exec(text)?.[1] ?? 2);
+  } catch {
+    return text;
+  }
+}
+
 /**
  * The project's thin flow (#552): a copy of an earlier release goes, then the manifest, the shim, the AGENTS.md block,
  * the cloud hook (#610), the package.json scripts, the files that led into the copy, the package version and the
@@ -1648,7 +1757,8 @@ function installProject(root: string, auto = autoOf(root), language = languageOf
   rewriteCopyRefs(root);
   packageDependency(root, ownVersion());
   gitignoreFlow(root);
-  if (!dry) copyLeftovers(root);
+  if (dry) copyRefs(root);
+  else copyLeftovers(root);
 }
 
 /**
@@ -2445,11 +2555,23 @@ function update(global: boolean) {
             `  git add -A -- ${add.map(shWord).join(" ")} && git commit -m "chore(agents): ${commitSubject(root, version)}"`,
           ]
         : []),
+      ...(copy ? ["By hand in the move's task:", ...MOVE_BY_HAND.map((l) => `  - ${l}`)] : []),
     ].join("\n"),
   );
   return 0;
 }
 
+/**
+ * What the move from a copy leaves by hand (#620) — `update` can't tell it from the text: `update` prints it after the
+ * move, its help names it; what still leads into the copy — `!` lines of `check` (`copyRefs`).
+ */
+const MOVE_BY_HAND = [
+  "a project's check that knows the queue wrapper by the copy's path: `. .agents/skills/slot/scripts/slot.sh && …` → `. .agents/slot.sh && …`",
+  `the queue variables under the former name in the project's code and configs: ${FORMER.slotEnv.join(", ")} → ${SLOT_ENV.join(", ")}`,
+  "imports that got shorter — the project's formatter",
+  "git add -A before the first run of the project's checks: until then git ls-files lists the copy's removed files",
+];
+
 /**
  * What the update brought, for the agent to tell the user: every release after the installed one up to this package's,
  * newest first — the tag, its page and the list its GitHub Release has (`changeItems`); no releases yet or an installer

package/claude/CLAUDE.md

@@ -7,8 +7,8 @@ every project, whatever its `CLAUDE.md`.
 - Session transcripts (`~/.claude/projects/<path-with-dashes>*/`) are the
   source of actuals for the `est` skill; `~/.claude/settings.json` must have
   `"cleanupPeriodDays": 365`, otherwise history is cleaned before it's needed.
-- The app's worktree names the branch `claude/<slug>-<hash>` — it is renamed
-  when the task is taken: `github task status <N> "In progress" --branch
+- The app's worktree names the branch `claude/<slug>-<hash>` — renamed when
+  the task is taken: `github task status <N> "In progress" --branch
   <type>/<N>-<slug>` (a bare `git branch -m` fails on `.git/config` locked by
   a parallel worktree and leaves the upstream behind). The session panel
   (branch, diff to `main`, "Create PR") reads git, not GitHub: after a merge
@@ -23,8 +23,8 @@ every project, whatever its `CLAUDE.md`.
   `ScheduleWakeup` on top: an armed wakeup keeps `archive_session` refused
   even after `stop`.
 - Merge in auto mode — `gh pr merge <N> --rebase` as a separate call, without
-  `cd`, `|`, `;`: otherwise the `Bash(gh pr merge *)` rule (set by the owner)
-  won't match and the classifier rejects the merge.
+  `cd`, `|`, `;`: otherwise the owner's `Bash(gh pr merge *)` rule won't
+  match and the classifier rejects the merge.
 - `install -g` puts a `SessionStart` hook into `~/.claude/settings.json`
   (`startup|resume|clear`): `check --hook` — the machine (canon, skills, hook)
   and the project's flow with its mode and language (`AGENTS.md`, "First step
@@ -42,7 +42,8 @@ every project, whatever its `CLAUDE.md`.
   with `self` archives it, ending the conversation: the last action, after
   the "can be closed" line. Before it — `TaskStop` for each own
   background task still running: a live one gives "still has live work".
-  Refused after that — don't retry: the owner archives from the sidebar.
+  A dispatcher archives an executor session with its id. Refused — don't
+  retry: the owner archives from the sidebar.
 - Skills — the machine's `~/.claude/skills/<name>` (symlinks to
   `~/.agents/skills/<name>`), a thin project has no others; the skill
   directory is `${CLAUDE_SKILL_DIR}`; a same-named machine skill wins over a
@@ -53,7 +54,7 @@ every project, whatever its `CLAUDE.md`.
   at once a separate call with `dangerouslyDisableSandbox`: no
   `excludedCommands` entry takes `bun <file>` out. Entries `gh *` and `bash
   <path>/wait-ci.sh *` (`ci-wait`) do — the owner's step; without them — the
-  same separate call. The `task-env` skill, section "Docker and the sandbox".
+  same separate call. The `task-env` skill, "Docker and the sandbox".
 - A subagent that writes gets `isolation: worktree`: an isolated session
   doesn't write into others' worktrees, an agent without it inherits the
   parent's isolation. An agent cut off (a limit, a dropped session) leaves
@@ -61,7 +62,7 @@ every project, whatever its `CLAUDE.md`.
   after a base change — dependencies from the lockfile, else typecheck runs
   on old packages.
 - In a cloud session (claude.ai/code) the cloud assigns the branch — rename
-  it or push to another one only with the user's permission
+  it or push elsewhere only with the user's permission
   (`docs/cloud-sessions.md`).
 - Another task isn't a session card (`spawn_task`, `start_session`): the
   question «queue #M?», on "yes" its executor — `Agent` with `isolation:

package/dist/github/scripts/github.js

@@ -1750,8 +1750,9 @@ function cloudBrief(io, slug, issue) {
   };
   for (const line of [N.queue.cloud, N.queue.cloudDoc, N.queue.cloudClose, N.queue.cloudDispatcher, N.queue.cloudQuestion])
     io.out(locale_default.fill(line, vars));
-  io.out(`Next: the lines above — the cloud session's first prompt as is, the session started from the project folder (the cloud starts from main); ` + `then as a background command: bash ${waitCi()} issue ${number} — a cloud session can't message a local one (docs/cloud-sessions.md), the task's closing is the signal: ` + `PASS — bun --no-env-file ${import.meta.path} task close ${number} (the actual with --write, ${STATUS}, the merged branch), then archive the executor's session where the agent has the tool; ` + `TIMEOUT — the task's ${q(N.sections.questions)} and its ${q(N.comments.state)} comment, the executor's session, then the same wait again`);
+  io.out(`Next: the lines above — the cloud session's first prompt as is, the session started from the project folder (the cloud starts from main); ` + `then as a background command: bash ${waitCi()} issue ${number} — a cloud session can't message a local one (docs/cloud-sessions.md), the task's closing is the signal: ` + `PASS — bun --no-env-file ${import.meta.path} task close ${number} (the actual with --write, ${STATUS}, the merged branch), then archive the executor's session in an auto project where the agent has the tool; ` + `TIMEOUT — the task's ${q(N.sections.questions)} and its ${q(N.comments.state)} comment, the executor's session, then the same wait again`);
 }
+var SESSION_ARCHIVE = "an executor session whose task closed — the dispatcher archives it in an auto project where the agent has the tool, " + "not one still working in the background or awaiting the owner's answer; outside auto the owner closes it";
 function cmdTaskQueue(io, slug, o) {
   const want = o.type === undefined ? undefined : typeAliases()[o.type.toLowerCase()];
   if (o.type !== undefined && (!want || want === N.issueTypes.epic))
@@ -1852,11 +1853,12 @@ function cmdTaskQueue(io, slug, o) {
   for (const line of waiting)
     io.out(line);
   if (ready.length) {
-    io.out(`Next: each ready task above — a background subagent in its own worktree while fewer than ${QUEUE_EXECUTORS} run (a number from the request replaces it); ` + "the indented line is its whole prompt. After each executor's answer — task queue again: new tasks get in.");
+    io.out(`Next: each ready task above — a background subagent in its own worktree while fewer than ${QUEUE_EXECUTORS} run (a number from the request replaces it); ` + `the indented line is its whole prompt. After each executor's answer — task queue again: new tasks get in; ${SESSION_ARCHIVE}.`);
   } else if (running.length)
-    io.out("Next: no ready tasks — wait for the executors' answers; after each — task queue again.");
-  else
-    io.out(`Queue is empty: nothing ready, nothing ${q(N.status.inProgress)} — the dispatcher's summary (merged, questions, the not ready ones above) and the last line; a session with its own task — after it.`);
+    io.out(`Next: no ready tasks — wait for the executors' answers; after each — task queue again; ${SESSION_ARCHIVE}.`);
+  else {
+    io.out(`Queue is empty: nothing ready, nothing ${q(N.status.inProgress)}; ${SESSION_ARCHIVE}. ` + "Then the dispatcher's summary (merged, questions, the not ready ones above) and the last line; a session with its own task — after it.");
+  }
   return 0;
 }
 var AGENT_WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]agent-[^\\/]+$/;

package/dist/spec/scripts/knip-hints.cjs

@@ -4,11 +4,13 @@
  * `{ "configurationHints": [{ type, identifier, workspace, file? }] }`. knip's `json` reporter doesn't print them,
  * and `--treat-config-hints-as-errors` gives only an exit code — the hints themselves aren't visible.
  *
- *   knip --reporter json --reporter .agents/skills/spec/scripts/knip-hints.cjs
+ *   knip --reporter json --reporter node_modules/@miroshnik/elves/skills/spec/scripts/knip-hints.cjs
  *
  * The second output line is its own: `deadCode` joins both. CommonJS, not TypeScript: the harness takes the file
  * path (`report.file`) with a static import — `import.meta` in a module that Playwright and Jest load as CommonJS is
- * a syntax error (tests/standards/harness-load); knip loads it under both Node and Bun. Types — `knip-hints.d.cts`.
+ * a syntax error (tests/standards/harness-load); knip loads it under both Node and Bun. A project's code takes the
+ * path the same way — the package's export `@miroshnik/elves/spec/knip-hints`, as is under Bun and Node, without a
+ * build (#620). Types — `knip-hints.d.cts`.
  */
 "use strict";
 

package/docs/cloud-sessions.md

@@ -179,8 +179,9 @@ i.e. per executor. So the brief tells the executor not to message the
 dispatcher and not to archive its session, and the dispatcher waits for the
 merge's `Closes #N`: `ci-wait issue <N>` as its own background command; PASS
 — `github task close <N>` locally (the actual with `--write`, `Status`, the
-merged `claude/<slug>` branch), then archiving the executor's session where
-it has the tool (till then its transcript may be needed for `est`); TIMEOUT —
+merged `claude/<slug>` branch), then archiving the executor's session in an
+auto project where it has the tool (till then its transcript may be needed
+for `est`; the rule — the `github` skill, "Dispatcher"); TIMEOUT —
 the task's questions section and State comment, the executor's session, the
 wait again. After the app restarts the queue's `=` line names the wait.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miroshnik/elves",
-  "version": "2026.1018.1",
+  "version": "2026.1018.2",
   "type": "module",
   "description": "Elves — a development flow with AI agents: shared rules and skills for any agent; install — bunx @miroshnik/elves install -g; the installer and skill scripts — TypeScript under Bun, tests — bun test in tests/",
   "repository": {
@@ -26,6 +26,10 @@
       "bun": "./skills/spec/scripts/eslint-config.ts",
       "default": "./dist/spec/scripts/eslint-config.js"
     },
+    "./spec/knip-hints": {
+      "types": "./skills/spec/scripts/knip-hints.d.cts",
+      "default": "./skills/spec/scripts/knip-hints.cjs"
+    },
     "./github": {
       "types": "./skills/github/scripts/github.ts",
       "bun": "./skills/github/scripts/github.ts",
@@ -66,5 +70,5 @@
     "eslint-plugin-boundaries": "^7.2.0",
     "knip": "^6.41.0"
   },
-  "gitHead": "28a9863fbdf5acfd5706b44b8d3c3ecd87fd39fd"
+  "gitHead": "40c5e0387c9bfa5dfb56d6a7f5b05a99333aabac"
 }

package/skills/github/SKILL.md

@@ -6,24 +6,23 @@ allowed-tools: Bash(bun *skills/github/scripts/github.ts *) Bash(git remote get-
 
 # github — project and tasks by the canon, not from memory
 
-Principles — `AGENTS.md`, section "Task tracking"; the full rules (types,
+Principles — `AGENTS.md`, "Task tracking"; the full rules (types,
 decision labels, epics, dependencies, the project, milestones, the five
 epic-refresh checks) and what each command below checks, sets and prints —
-`reference.md` next to this file. Done by hand from the reference, projects
-drift apart and a task gets created without a status, priority or epic link.
+`reference.md` next to this file. By hand, projects drift apart and tasks
+lack a status, priority or epic link.
 The script `scripts/github.ts` next to this file checks the project
 against the canon, fixes what the API can, and does each task step in one
 command; the agent goes through the UI steps and asks for confirmation on
 anything destructive. Syntax and a summary of a command —
 `github <command> --help`. Editing an existing task (Priority, links) and
-milestones — `reference.md`, section "Manual commands".
+milestones — `reference.md`, "Manual commands".
 
 **In Claude Code — at once a separate unsandboxed call**
 (`dangerouslyDisableSandbox`): `gh` fails on TLS in the sandbox, `task close`
 also calls Docker for the task's stacks — the sandbox denies its socket, and
-no `excludedCommands` entry takes a script run by `bun` out — checked with
-`bun <path>/github.ts project check` too (`claude/CLAUDE.md`; `SKILL.md` of the
-task-env skill, "Checked on the machine").
+no `excludedCommands` entry takes a script run by `bun` out
+(`claude/CLAUDE.md`; `SKILL.md` of the task-env skill, "Checked on the machine").
 
 ## Project — check and fix
 
@@ -54,8 +53,8 @@ asking separately; no browser or sign-in — a list of steps with links for the
 user; the agent doesn't enter a password; after the steps — `check` again;
 **Confirmation needed** — show the list to the user, after a "yes" —
 `fix --confirm`; `!` — an error with the reason, most often `gh` lacks a
-scope. The eleven items checked, who does what, how to go through the UI steps
-and the API's gaps — `reference.md`, "Project check and fix".
+scope. The eleven items checked, who does what, the UI steps and the API's
+gaps — `reference.md`, "Project check and fix".
 
 ## Tasks and PRs
 
@@ -84,7 +83,7 @@ bun --no-env-file <skill dir>/scripts/github.ts pr premerge <PR>
 | PR merged | in one turn — `task actualize N` and in the background `wait-ci.sh merged <PR>` (it takes the merge SHA itself); a refresh is needed — next turn, in the background, a subagent with the printed two-line prompt; after both — `task close N` (exit code 0 from the wait — right away, don't read the output) |
 | Task closed without a PR | `task actualize N`, the subagent; then `task close N` |
 | Session resumed after the app restarted | the `SessionStart` hook runs `task resume` itself — its line is in the context: run the named command, a background wait died with the process |
-| "Do all tasks of epic #M", "fix all High bugs", a new epic — the owner's "yes" | the session is a dispatcher, its own task stays: `task queue --epic M` (or `--type`, `--priority`), executors — background subagents; below, "Dispatcher" |
+| "Do all tasks of epic #M", "fix all High bugs", a new epic — the owner's "yes" | the session is a dispatcher, its own task stays: `task queue --epic M` (or `--type`, `--priority`); below, "Dispatcher" |
 | Another task: work outside the task, a red-main bug, a flow copy's move | `task new`, then the question to the owner «queue #N?»; "yes" — its executor at once, the same as a dispatcher's (`task new` and `task status` in a session with a task print its prompt) |
 | Won't do, duplicate, replaced by others | `task drop N [--duplicate-of M]` |
 | PR ready (and after new commits) | `pr labels <PR>` — decision labels for the task and the epic |
@@ -151,26 +150,28 @@ folder, not a worktree: executors (subagents, cloud sessions) start from
 tasks, each with an indented line — its executor's prompt. In Claude Code: an executor — `Agent` with
 `isolation: "worktree"` and `run_in_background: true`, the prompt — the
 indented line as is; at most 3 subagents and 5 cloud sessions at once, the
-owner's number replaces either;
+owner's number replaces either; another project's task — an app session in
+its folder (`start_session`, own worktree);
 `=` — a task in work (In progress, an open PR, handed out to an executor of
 this session), not launched again. Before each launch — `get_usage`: the 5-hour limit at 85% and more —
 no new executors, the running ones finish, then `Remaining: N tasks, the
-limit`. After each executor's answer — `task queue` again: it also removes
-finished executors' worktrees (`+`), not by hand. A question — to the
+limit`. After each executor's answer — `task queue` again: it removes
+finished executors' worktrees (`+`); its last line names the step:
+an executor session whose task closed — the dispatcher archives it in an
+auto project, not one still working in the background or awaiting the
+owner's answer; outside auto the owner closes it. A question — to the
 owner in text; the answer — ✅ in the task's questions section and to the same
 executor with `SendMessage`. After the app restarts — each stopped executor
-is continued with `SendMessage` by its id, not a new one (`task resume`). Waits for subagents — it answers again. Failed — a
-task comment with what stopped, no restart (the owner's restart:
-`--assignment` refuses while the previous executor lives); on an external
-blocker — *blocked by* on its issue or
-the `external blocker` label with the reason (`reference.md`,
-"Dependencies"). Queue empty and nothing running — the summary, the last
+is continued with `SendMessage` by its id, not replaced (`task resume`). Waits for subagents — it answers again. Failed — a
+task comment, no restart (the owner's restart:
+`--assignment` refuses while the previous executor lives); external
+blockers — `reference.md`, "Dependencies". Queue empty and nothing running — the summary, the last
 line (a session with its own task — after it) and, in auto mode, archiving. The executor's side (`--assignment`,
 a cloud one's: `--cloud`) — `reference.md`, "task queue".
 
 ## Git, PRs and merging — mechanics
 
-Principles — `AGENTS.md`, section "Git, PRs and merging"; the full rules —
+Principles — `AGENTS.md`, "Git, PRs and merging"; the full rules —
 `reference.md`, "Git, PRs and merging — full rules". Waiting for checks, the
 full SHA and a merge that deploys — `docs/pr-checks.md`.
 

package/skills/github/reference.md

@@ -809,10 +809,30 @@ stops giving the task out until it's lifted. Queue
 empty and nothing running — the summary (merged, questions, not ready, new
 tasks outside the queue), the last line and, in auto mode, archiving; a session
 with its own task — after it. A running executor isn't stopped (`TaskStop`) to
-archive the session: its answer comes first. The app's
-child sessions (`start_session`) aren't given out yet (a server flag); when
-they are, an executor becomes a session. A cloud executor (claude.ai/code,
-#609) — `--assignment N --cloud`, called by the dispatcher itself: the brief,
+archive the session: its answer comes first.
+
+The app's sessions are executors too: another project's task — an app session
+in its folder (`start_session` with its own worktree), while a subagent works
+in a worktree of the dispatcher's repository. Such a session works as a session
+of its project, by its mode; the end of its turn comes as the app's note, like
+an answer, — `task queue` again. Archiving, app and cloud executors alike
+(#621): an executor session whose task closed — the dispatcher archives it in
+an auto project, not one still working in the background or awaiting the
+owner's answer; outside auto the owner closes it. Closed — `task close` passed:
+the PR merged, the deploy green, the actual written; the session is still in
+the list. Auto — `"auto": true` in `.agents/elves.json` of the session's
+project. In auto mode a session archives itself after the last line, but not
+always: it ended with a question whose answer went to the dispatcher, or its
+last turn was the wait for the deploy, and the line never reached archiving.
+Not archived: a session with live background work (the app refuses — "still
+has live work"), one awaiting the owner's answer (an archived session leaves
+the list, and the owner wouldn't read its question), a project outside auto
+mode — the owner closes those. The step — the last line of `task queue`, read
+after each answer; in Claude Code — `archive_session` with the session's id,
+refused — not retried (`claude/CLAUDE.md`).
+
+A cloud executor (claude.ai/code, #609) — `--assignment N --cloud`, called by
+the dispatcher itself: the brief,
 the cloud session's first prompt as is — whole, `task queue` refuses in
 the cloud; `#` only at its task (`docs/cloud-sessions.md`, "The
 brief"); after the merge — the cloud's close, without messaging the
@@ -820,7 +840,8 @@ dispatcher or archiving its session. The hand-out — without a worktree
 (`@cloud`). A cloud session can't message a local one, so `Next:` gives the
 dispatcher the wait for the task's closing — `wait-ci.sh issue N` as a
 background command; PASS — `task close N`, then archiving the executor's
-session; TIMEOUT — the task's questions and State comment, the wait again;
+session in an auto project (above); TIMEOUT — the task's questions and State
+comment, the wait again;
 after the app restarts the queue's `=` line names the wait.
 
 ### task drop

package/skills/github/scripts/github.ts

@@ -2350,11 +2350,23 @@ function cloudBrief(io: Io, slug: string, issue: Issue): void {
   io.out(
     `Next: the lines above — the cloud session's first prompt as is, the session started from the project folder (the cloud starts from main); ` +
       `then as a background command: bash ${waitCi()} issue ${number} — a cloud session can't message a local one (docs/cloud-sessions.md), the task's closing is the signal: ` +
-      `PASS — bun --no-env-file ${import.meta.path} task close ${number} (the actual with --write, ${STATUS}, the merged branch), then archive the executor's session where the agent has the tool; ` +
+      `PASS — bun --no-env-file ${import.meta.path} task close ${number} (the actual with --write, ${STATUS}, the merged branch), then archive the executor's session in an auto project where the agent has the tool; ` +
       `TIMEOUT — the task's ${q(N.sections.questions)} and its ${q(N.comments.state)} comment, the executor's session, then the same wait again`,
   );
 }
 
+/**
+ * The dispatcher's step for its executor sessions — the app's (`start_session`: another project's task) and cloud ones
+ * (#621). In auto mode a session archives itself after the last line, but not always: it ended with a question whose
+ * answer went to the dispatcher, or its last turn was the wait for the deploy. The queue is what the dispatcher reads
+ * after each executor's answer, so its `Next:` names the step. Not archived: a session with live background work (the
+ * app refuses), one awaiting the owner's answer (an archived session leaves the list, and the owner wouldn't read its
+ * question), a project outside auto mode — the owner closes those.
+ */
+const SESSION_ARCHIVE =
+  "an executor session whose task closed — the dispatcher archives it in an auto project where the agent has the tool, " +
+  "not one still working in the background or awaiting the owner's answer; outside auto the owner closes it";
+
 /**
  * The dispatcher's queue: its ready tasks go to background executors (subagents), K at a time; the queue is re-read
  * after each answer, so tasks that appeared meanwhile are picked up. A session with its own task dispatches too (#546:
@@ -2364,6 +2376,7 @@ function cloudBrief(io: Io, slug: string, issue: Issue): void {
  * "Closes #N" among recent PRs) named with its link, or handed out to an executor of this session (`handedOutFile`).
  * Marks the session as a dispatcher (`dispatcherFile`). Before the queue — finished agents' worktrees
  * (`pruneAgentWorktrees`) but those of executors whose handed-out tasks are open and those a subagent still works in.
+ * The last line names archiving finished executor sessions (`SESSION_ARCHIVE`).
  */
 export function cmdTaskQueue(io: Io, slug: string, o: QueueFilter): number {
   const want = o.type === undefined ? undefined : typeAliases()[o.type.toLowerCase()];
@@ -2453,10 +2466,15 @@ export function cmdTaskQueue(io: Io, slug: string, o: QueueFilter): number {
   if (ready.length) {
     io.out(
       `Next: each ready task above — a background subagent in its own worktree while fewer than ${QUEUE_EXECUTORS} run (a number from the request replaces it); ` +
-        "the indented line is its whole prompt. After each executor's answer — task queue again: new tasks get in.",
+        `the indented line is its whole prompt. After each executor's answer — task queue again: new tasks get in; ${SESSION_ARCHIVE}.`,
     );
-  } else if (running.length) io.out("Next: no ready tasks — wait for the executors' answers; after each — task queue again.");
-  else io.out(`Queue is empty: nothing ready, nothing ${q(N.status.inProgress)} — the dispatcher's summary (merged, questions, the not ready ones above) and the last line; a session with its own task — after it.`);
+  } else if (running.length) io.out(`Next: no ready tasks — wait for the executors' answers; after each — task queue again; ${SESSION_ARCHIVE}.`);
+  else {
+    io.out(
+      `Queue is empty: nothing ready, nothing ${q(N.status.inProgress)}; ${SESSION_ARCHIVE}. ` +
+        "Then the dispatcher's summary (merged, questions, the not ready ones above) and the last line; a session with its own task — after it.",
+    );
+  }
   return 0;
 }
 

package/skills/spec/checks.md

@@ -534,7 +534,10 @@ monorepo knip takes longer than a test timeout (5 s in Vitest). Without
 `node_modules/.bin/knip --reporter json --reporter <skill>/knip-hints.cjs` is
 run (plus `args`); `report` is ready output of the same command (`knip --reporter
 json --reporter node_modules/@miroshnik/elves/skills/spec/scripts/knip-hints.cjs > .knip.json`);
-without the hints line — a failed test with that command. An exit code other
+without the hints line — a failed test with that command. A project's code that
+needs the reporter's path takes it from the reporter itself, not as a string into
+`node_modules`: `import knipHints from "@miroshnik/elves/spec/knip-hints"` —
+`knipHints.file`, under Bun and Node. An exit code other
 than 0/1 or output that isn't JSON — all the kind tests fail with the reason: a
 knip crash isn't "no dead code".
 

package/skills/spec/scripts/knip-hints.cjs

@@ -4,11 +4,13 @@
  * `{ "configurationHints": [{ type, identifier, workspace, file? }] }`. knip's `json` reporter doesn't print them,
  * and `--treat-config-hints-as-errors` gives only an exit code — the hints themselves aren't visible.
  *
- *   knip --reporter json --reporter .agents/skills/spec/scripts/knip-hints.cjs
+ *   knip --reporter json --reporter node_modules/@miroshnik/elves/skills/spec/scripts/knip-hints.cjs
  *
  * The second output line is its own: `deadCode` joins both. CommonJS, not TypeScript: the harness takes the file
  * path (`report.file`) with a static import — `import.meta` in a module that Playwright and Jest load as CommonJS is
- * a syntax error (tests/standards/harness-load); knip loads it under both Node and Bun. Types — `knip-hints.d.cts`.
+ * a syntax error (tests/standards/harness-load); knip loads it under both Node and Bun. A project's code takes the
+ * path the same way — the package's export `@miroshnik/elves/spec/knip-hints`, as is under Bun and Node, without a
+ * build (#620). Types — `knip-hints.d.cts`.
  */
 "use strict";
 

package/skills/task-env/SKILL.md

@@ -27,7 +27,9 @@ bun --no-env-file <skill dir>/scripts/task-env.ts check [<dir>]  # the compose f
 ```
 
 Each command's details and examples — `--help` after it; the details behind this file — `reference.md` next to it.
-Run the script outside the sandbox — section "Docker and the sandbox".
+Run the script outside the sandbox — section "Docker and the sandbox". A project's own scripts and tests (the stack
+before the dev server, the e2e wrapper, a compose isolation test) run it from the project's package, at its Elves
+version — `bun --no-env-file node_modules/.bin/elves task-env up` — not by a path into a skill directory.
 
 The skill's `check -g` line: `proxy *.localhost: running (elves-proxy)`,
 `not running — start: …` or `Docker unavailable — <reason>`; no Docker on the

package/skills/task-env/scripts/task-env.ts

@@ -53,9 +53,11 @@ import { fileURLToPath } from "node:url";
 /**
  * Help — `--help` or `-h` before `--` (after it — the e2e command's arguments; tests/standards/cli-help): a command's
  * synopsis (the first paragraph), what it does and examples; `task-env --help` — the synopses of all. The dispatcher takes
- * only the commands from here: a command without help can't be called.
+ * only the commands from here: a command without help can't be called. A project's scripts and tests run it from the
+ * project's package — `elves task-env …` (bin/elves.ts imports `main`, `HELP` and `OVERVIEW` and prints them under its
+ * name, #620).
  */
-const HELP: Record<string, string> = {
+export const HELP: Record<string, string> = {
   up: `task-env up [--profile <p>]...
 
 Brings the task's stack up — the Compose project <project>-<N> by the branch <type>/<N>-slug, <project> without a
@@ -125,7 +127,7 @@ Examples:
 };
 
 /** `task-env --help`: what the script is and the synopsis of each command. */
-const OVERVIEW = [
+export const OVERVIEW = [
   "task-env — a task's environment: its Docker Compose stack and the machine's proxy of *.localhost addresses",
   "",
   ...Object.values(HELP).map((h) => h.split("\n\n")[0]!.replace(/^/gm, "  ")),
@@ -961,7 +963,7 @@ function stackCommand(group: string, args: string[], env: NodeJS.ProcessEnv): nu
 
 const COMMANDS: Record<string, (env: NodeJS.ProcessEnv) => Result> = { up, down, status };
 
-function main(argv: string[]): number {
+export function main(argv: string[]): number {
   const help = helpOf(argv);
   if (help) return process.stdout.write(help + "\n"), 0;
   const command = commandOf(argv);