@litfamily/litopencode 1.0.33 → 1.0.35

package/dist/cli/install.js

@@ -13,6 +13,7 @@ import { renderLitOpenCodeWordmark } from "./install-tui.js";
 import { promptModelSelection, promptOutputStyle, promptPermissionMode } from "./model-routing.js";
 import { litOpenCodeConfigFileForOpenCodeRoot } from "../state.js";
 import { describeNativeSkillMutation, ensureNativeSkills, inspectNativeSkills } from "./native-skills.js";
+import { installAgentFile, planAgentFile } from "./agent-file-command.js";
 import { applyPluginMutation, describePluginMutation, isLitOpenCodeEntry } from "./plugin-mutation.js";
 import { prewarmMotionRuntime } from "./motion-runtime.js";
 import { applyCliJsonCleanup, applyTuiWrites, backupTuiFiles, inspectTuiPlugin, planCliJsonCleanup, planTuiInstall, skippedTuiPlan } from "./tui-config.js";
@@ -257,7 +258,7 @@ async function verifyInstalledSurfaces(root, configFile, target, metadata, selec
     if (failures.length > 0)
         throw new Error("Install verification failed: " + failures.join("; "));
 }
-export async function install(root, dryRun, modelSelection = undefined, modelPrompt = "auto", permissionMode = "safe", permissionModeExplicit = false, permissionPrompt = "auto", progress, outputStylePrompt = "auto", host = "auto") {
+export async function install(root, dryRun, modelSelection = undefined, modelPrompt = "auto", permissionMode = "safe", permissionModeExplicit = false, permissionPrompt = "auto", progress, outputStylePrompt = "auto", host = "auto", agentFileChoice = { assumeYes: false, skip: false }) {
     const retiredNotice = await migrateRetiredEfforts(root, dryRun);
     if (retiredNotice !== undefined)
         process.stdout.write(retiredNotice + "\n");
@@ -336,10 +337,12 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
     }
     const { configFile, before, mutation, litopencodeConfig, commandAliases, nativeSkills, hostLimits, routes, tui, cliJson } = inspected;
     const v2PluginsChanged = resolved.forV2 && withoutV2PluginEntries(before) !== before;
+    const agentFileInput = { root, version: metadata.version, ...agentFileChoice };
     const report = {
         dryRun,
         path: configFile,
         litopencodeConfig,
+        ...(dryRun ? { agentFile: await planAgentFile(agentFileInput) } : {}),
         plugin: mutation.plugin,
         commandAliases,
         nativeSkills,
@@ -423,12 +426,14 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
         await applyCliJsonCleanup(cliJson);
     await withProgress(activeProgress, "Verify install", async () => verifyInstalledSurfaces(root, configFile, resolved.target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle, resolved.detection));
     await activeProgress?.complete();
+    // The block is the last step: it asks a question, and a refusal here never undoes a finished install.
+    const agentFileLine = wrapReceiptLine(await installAgentFile(agentFileInput));
     // MO-A-42: the installer attempts the motion pre-warm; a failure never fails the install.
     const motionReceipt = wrapReceiptLine(prewarmMotionRuntime(metadata.packageRoot));
     return {
         exitCode: 0,
         stdout: activeProgress === undefined
-            ? renderLitOpenCodeWordmark(pluginSpec(metadata), false) + "\n" + renderInstallReport(report) + "\n" + motionReceipt
-            : motionReceipt
+            ? renderLitOpenCodeWordmark(pluginSpec(metadata), false) + "\n" + renderInstallReport(report) + "\n" + agentFileLine + "\n" + motionReceipt
+            : agentFileLine + "\n" + motionReceipt
     };
 }

package/dist/cli/managed-block.d.ts

@@ -0,0 +1,26 @@
+export declare class ManagedBlockError extends Error {
+}
+export type ManagedBlock = {
+    readonly id: string;
+    readonly version: string;
+    readonly body: string;
+};
+export type BlockInspection = {
+    readonly state: "absent" | "present" | "malformed";
+    readonly version: string | null;
+    readonly created: boolean;
+};
+export declare function inspectBlock(text: string, id: string): BlockInspection;
+/** Adds the block, or swaps the bytes between an existing block's markers. `created` marks a file made for the block. */
+export declare function upsertBlock(text: string, block: ManagedBlock, options?: {
+    readonly created?: boolean;
+}): {
+    text: string;
+    changed: boolean;
+};
+/** Removes the block, the line ending after it and whatever was added in front of it. */
+export declare function removeBlock(text: string, id: string): {
+    text: string;
+    changed: boolean;
+    created: boolean;
+};

package/dist/cli/managed-block.js

@@ -0,0 +1,80 @@
+// A LitFamily block inside a file the user owns (OpenCode's global AGENTS.md, a repo's AGENTS.md): the
+// lines between `<!-- litfamily:<id>:start v=<version> -->` and `<!-- litfamily:<id>:end -->`. Only those
+// lines are written. The start marker also records what was put in front of the block (`pre=`, hex) and
+// whether the file was made for it (`new=1`), so removing the block takes back exactly that and an
+// add-then-remove returns the original bytes under any line ending. A start without its end, or two of
+// either, is malformed and refused rather than guessed at.
+import { Buffer } from "node:buffer";
+export class ManagedBlockError extends Error {
+}
+const startOf = (id) => `<!-- litfamily:${id}:start`;
+const endOf = (id) => `<!-- litfamily:${id}:end -->`;
+const startLine = /^<!-- litfamily:[^:\s]+:start v=(\S+)((?: [a-z]+=[0-9a-f]*)*) -->/u;
+function lineEnding(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+function positionsOf(text, needle) {
+    const found = [];
+    for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length))
+        found.push(at);
+    return found;
+}
+function locate(text, id) {
+    const starts = positionsOf(text, startOf(id));
+    const ends = positionsOf(text, endOf(id));
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0]) {
+        throw new ManagedBlockError(`malformed LitFamily ${id} block: expected one start marker followed by one end marker`);
+    }
+    const head = startLine.exec(text.slice(starts[0]));
+    if (head === null)
+        throw new ManagedBlockError(`malformed LitFamily ${id} block: unreadable start marker`);
+    const attributes = new Map(head[2].trim().split(" ").filter(Boolean).map((pair) => pair.split("=")));
+    const pre = attributes.get("pre");
+    return {
+        start: starts[0],
+        end: ends[0] + endOf(id).length,
+        version: head[1],
+        pre: pre === undefined || pre === "" ? "" : Buffer.from(pre, "hex").toString("utf8"),
+        created: attributes.get("new") === "1"
+    };
+}
+function render(block, eol, added) {
+    const attributes = `${added.pre === "" ? "" : ` pre=${Buffer.from(added.pre, "utf8").toString("hex")}`}${added.created ? " new=1" : ""}`;
+    const body = block.body.replace(/\r?\n$/u, "").split(/\r?\n/u);
+    return [`${startOf(block.id)} v=${block.version}${attributes} -->`, ...body, endOf(block.id)].join(eol);
+}
+export function inspectBlock(text, id) {
+    try {
+        const span = locate(text, id);
+        return span === null ? { state: "absent", version: null, created: false } : { state: "present", version: span.version, created: span.created };
+    }
+    catch {
+        return { state: "malformed", version: null, created: false };
+    }
+}
+/** Adds the block, or swaps the bytes between an existing block's markers. `created` marks a file made for the block. */
+export function upsertBlock(text, block, options = {}) {
+    const eol = lineEnding(text);
+    const span = locate(text, block.id);
+    if (span !== null) {
+        const next = text.slice(0, span.start) + render(block, eol, span) + text.slice(span.end);
+        return { text: next, changed: next !== text };
+    }
+    const pre = text === "" ? "" : (text.endsWith("\n") ? "" : eol) + eol;
+    return { text: text + pre + render(block, eol, { pre, created: options.created === true }) + eol, changed: true };
+}
+/** Removes the block, the line ending after it and whatever was added in front of it. */
+export function removeBlock(text, id) {
+    const span = locate(text, id);
+    if (span === null)
+        return { text, changed: false, created: false };
+    let before = text.slice(0, span.start);
+    let after = text.slice(span.end);
+    const eol = after.startsWith("\r\n") ? "\r\n" : after.startsWith("\n") ? "\n" : "";
+    after = after.slice(eol.length);
+    if (span.pre !== "" && before.endsWith(span.pre))
+        before = before.slice(0, -span.pre.length);
+    return { text: before + after, changed: true, created: span.created };
+}

package/dist/cli/model-routing.d.ts

@@ -1,5 +1,10 @@
 import type { InstallModelSelection, InstallPermissionChoice, InstallPermissionMode, ModelConfigClassification, ModelPromptMode, PermissionPromptMode } from "./types.ts";
 export declare function promptOutputStyle(existing: string, promptMode: PermissionPromptMode, dryRun: boolean): Promise<string>;
+export type PromptReader = {
+    question(prompt: string): Promise<string>;
+    close(): void;
+};
+export declare function createPromptReader(): PromptReader;
 export declare function promptPermissionMode(selected: InstallPermissionMode, mode: PermissionPromptMode, dryRun: boolean): Promise<InstallPermissionChoice>;
 export declare function renderModelRouteCard(selection: InstallModelSelection, configPath: string): string;
 export declare function promptModelSelection(selection: InstallModelSelection | undefined, mode: ModelPromptMode, dryRun: boolean, classification: ModelConfigClassification, configPath: string, currentSelection?: InstallModelSelection | undefined): Promise<InstallModelSelection | undefined>;

package/dist/cli/model-routing.js

@@ -57,7 +57,7 @@ function formatChoice(index, label, hint) {
 async function askLine(reader, prompt) {
     return (await reader.question(prompt)).trim();
 }
-function createPromptReader() {
+export function createPromptReader() {
     if (process.stdin.isTTY === true) {
         return readline.createInterface({ input: process.stdin, output: process.stdout, terminal: markColorMode() !== "none" });
     }

package/dist/cli/types.d.ts

@@ -28,6 +28,10 @@ export type ParsedArgs = {
     readonly outputStylePrompt: PermissionPromptMode;
     readonly loop: LoopArgs;
     readonly tuiAction?: string;
+    readonly agentFileAction?: string;
+    readonly agentFileDir?: string;
+    readonly agentFile: "auto" | "skip";
+    readonly assumeYes: boolean;
     readonly host: HostChoice;
 };
 export type LoopArgs = {
@@ -158,6 +162,12 @@ export type InstallReport = {
             readonly changed: boolean;
         };
     };
+    readonly agentFile?: {
+        readonly path: string;
+        readonly state: string;
+        readonly mode: string;
+        readonly action: string;
+    };
     readonly plugin: PluginMutation["plugin"];
     readonly commandAliases: {
         readonly path: string;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { isLoopCommand, parseArgs } from "./cli/args.js";
 import { runLoopCommand } from "./cli/loop.js";
 import { doctor } from "./cli/doctor.js";
+import { runAgentFileCommand } from "./cli/agent-file-command.js";
 import { install } from "./cli/install.js";
 import { createInstallTui, renderLitOpenCodeWordmark, shouldRenderInstallTui } from "./cli/install-tui.js";
 import { runUpdateNotifier } from "./cli/update-notifier.js";
@@ -33,7 +34,10 @@ function helpText() {
         "  litopencode install [--dry-run] [--root <dir>] --provider <openai|xai> --model <id> [--effort <e>] [--subagent-model <provider/id>] [--subagent-effort <e>] [--yolo]",
         "  litopencode install [--model-prompt | --no-model-prompt | --yes]",
         "  litopencode install [--permission-prompt | --no-permission-prompt] [--permission-mode <safe|balanced|yolo>]",
+        "  litopencode install [--no-agent-file]",
         "  litopencode install|doctor [--no-auto-update]",
+        "  litopencode agent-file on|off|remove [--dry-run] [--root <dir>]",
+        "  litopencode agent-file project [--dir <path>] [--dry-run]",
         "  litopencode doctor [--json] [--root <dir>]",
         "  litopencode tui remove [--dry-run] [--root <dir>]",
         "  litopencode motion-runtime install|status [--audio] [--word-timing] [--dry-run] (install) [--json] (status)",
@@ -54,6 +58,7 @@ function helpText() {
         "Commands:",
         "  install       Register litopencode with OpenCode using a branded installer UI.",
         "  doctor        Report package, config, and runtime path status without writing files.",
+        "  agent-file    Add, remove or switch off the short LitFamily block in OpenCode's global AGENTS.md; project writes it into a repo's AGENTS.md.",
         "  tui remove    Remove only LitOpenCode's TUI panel entry from tui.json/tui.jsonc (backed up first).",
         "  fetch-public  Fetch a public URL with SSRF guards, verdicts, and trace output.",
         "                --allow-private-network is opt-in for reviewed local fixtures or trusted internal tests.",
@@ -121,6 +126,12 @@ function helpText() {
         "  --no-auto-update or LITOPENCODE_NO_AUTO_UPDATE=1 disables the barrier; NO_UPDATE_NOTIFIER and LITOPENCODE_NO_UPDATE_CHECK also disable it.",
         "  The detached update notice remains cache-refresh-only and never installs.",
         "",
+        "LitFamily block:",
+        "  An interactive install asks once whether to add a short, marker-delimited block to <root>/AGENTS.md, the global file OpenCode reads every session.",
+        "  --yes adds it; --no-agent-file skips it for one run; a non-interactive install without --yes never writes it. Your own text stays byte for byte.",
+        "  OpenCode reads ~/.claude/CLAUDE.md only while <root>/AGENTS.md is missing, so the installer never creates AGENTS.md over an existing CLAUDE.md.",
+        "  agent-file off removes the block and stores the choice in litopencode.json; agent-file remove only removes it. doctor prints the block state.",
+        "",
         "Default root:",
         "  ~/.config/opencode, or $XDG_CONFIG_HOME/opencode when XDG_CONFIG_HOME is set."
     ].join("\n");
@@ -146,6 +157,8 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return await runLoopCommand(parsed.command, parsed.loop, parsed.dryRun);
         if (parsed.command === "doctor")
             return await doctor(parsed.root, parsed.host);
+        if (parsed.command === "agent-file")
+            return await runAgentFileCommand(parsed, (await readPackageMetadata()).version);
         if (parsed.command === "tui") {
             const removed = await removeTuiEntries(parsed.root, parsed.dryRun, { cliJson: parsed.host !== "v1" });
             return { exitCode: 0, stdout: JSON.stringify(removed, null, 2) };
@@ -163,7 +176,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return { exitCode: output.ok ? 0 : 1, stdout: renderFetchPublicText(output) };
         }
         if (parsed.command === "install") {
-            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt, parsed.host);
+            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt, parsed.host, { assumeYes: parsed.assumeYes, skip: parsed.agentFile === "skip" });
         }
         return { exitCode: 2, stderr: `Unknown command: ${parsed.command}` };
     }

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.33"><title>release: 1.0.33</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.33</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.35"><title>release: 1.0.35</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.35</text></g></svg>

package/docs/reference-Ko-KR.md

@@ -53,6 +53,32 @@ npm exec --package @litfamily/litopencode@latest -- litopencode doctor
 그대로 둡니다. 기본 OpenCode 설정 파일은 `~/.config/opencode/opencode.jsonc`입니다.
 `XDG_CONFIG_HOME`이 설정되어 있으면 `$XDG_CONFIG_HOME/opencode/opencode.jsonc`를 사용합니다.
 
+### 전역 AGENTS.md 블록
+
+OpenCode의 Rules 문서는 `~/.config/opencode/AGENTS.md`를 전역 규칙 파일로 적고, OpenCode는 그 폴더를
+`$XDG_CONFIG_HOME`에서 만듭니다(`OPENCODE_CONFIG_DIR`은 위치를 바꾸지 않으며, `opencode debug paths`로 확인할 수
+있습니다). 설치 도구는 다른 모든 곳에서 쓰는 것과 같은 root의 `<root>/AGENTS.md`에 쓰므로 `--root`와
+`XDG_CONFIG_HOME`이 그대로 따라갑니다. `<!-- litfamily:litopencode:start v=<version> -->`와
+`<!-- litfamily:litopencode:end -->` 사이의 줄만 씁니다. 시작 표시에는 블록 앞에 덧붙인 내용도 기록해 두므로,
+블록을 빼면 LF든 CRLF든 원래 바이트로 돌아갑니다. 쓰기는 임시 파일과 rename으로 하고, 두 번째 설치는 아무것도
+바꾸지 않으며 새 백업도 만들지 않습니다.
+
+| 명령 | 효과 |
+| --- | --- |
+| `install` (대화형) | 한 번 묻고 기본값은 예입니다. 아니오를 고르면 `litopencode.json`에 `"agentFile": "off"`를 저장합니다. |
+| `install --yes` | `agentFile`이 `off`가 아니면 블록을 넣거나 갱신합니다. |
+| `install --no-agent-file` | 이번 실행에서만 파일을 그대로 두고 아무것도 저장하지 않습니다. |
+| `install` (터미널 없음, `--yes` 없음) | 블록을 새로 넣지 않습니다. 이미 있는 이전 블록은 제자리에서 갱신합니다. |
+| `agent-file on` / `off` | 설정을 저장하고 블록을 바로 넣거나 뺍니다. |
+| `agent-file remove` | 블록을 빼고, 설치가 만든 파일이면 파일도 지웁니다. 저장된 설정은 그대로입니다. |
+| `agent-file project [--dir <path>]` | 해당 폴더의 `AGENTS.md`에 프로젝트 블록을 쓰며 백업 복사본은 만들지 않습니다. |
+| `doctor` | `agentFile.state`는 `present v=<x>`, `stale v=<x>`, `absent`, `off`, `malformed`, `symlink`, `not-file`, `not-utf8` 중 하나입니다. |
+
+`LITOPENCODE_AGENT_FILE=on|off`는 저장된 설정보다 우선합니다. 표시 쌍이 깨졌거나, 심볼릭 링크이거나, 폴더이거나,
+UTF-8이 아닌 파일은 `refused-*`로 알리고 그대로 둡니다. `<root>/AGENTS.md`가 없고 `~/.claude/CLAUDE.md`가 있으면
+OpenCode는 자기 전역 파일이 없을 때만 그 Claude 파일을 읽으므로 아무것도 만들지 않습니다
+(`skipped-claude-fallback`). `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1`이면 이 보호는 풀립니다.
+
 *OpenCode의 이벤트가 플러그인으로 들어오면 TypeScript runtime이 route와 권한 경계를 적용하고, tool guard와 durable ledger로 결과를 남깁니다. 아래 흐름이 설치 후 실제로 연결되는 host surface입니다.*
 
 ```mermaid
@@ -263,6 +289,7 @@ flowchart LR
 npm uninstall -g @litfamily/litopencode
 ```
 
+설치가 전역 `AGENTS.md`에 LitFamily 블록을 넣었다면 그 전에 `litopencode agent-file remove`를 실행하세요.
 그 다음 OpenCode가 관리하는 `opencode.jsonc`(또는 custom root의 `opencode.json`)의
 `plugin` 배열에서 `@litfamily/litopencode` 또는 `@litfamily/litopencode@<version>` 항목을 제거합니다.
 더 이상 route가 필요하지 않을 때만 `~/.config/opencode/litopencode.json`을 제거하세요.

package/docs/reference.md

@@ -54,6 +54,32 @@ routes remain user-owned. The default OpenCode config is
 `~/.config/opencode/opencode.jsonc`, or `$XDG_CONFIG_HOME/opencode/opencode.jsonc`
 when `XDG_CONFIG_HOME` is set.
 
+### Global AGENTS.md block
+
+OpenCode's Rules page names `~/.config/opencode/AGENTS.md` as the global rules file, and OpenCode builds that
+folder from `$XDG_CONFIG_HOME` (`OPENCODE_CONFIG_DIR` does not move it; `opencode debug paths` prints it). The
+installer writes to `<root>/AGENTS.md` for the same root it uses everywhere else, so `--root` and
+`XDG_CONFIG_HOME` carry over. Only the lines between `<!-- litfamily:litopencode:start v=<version> -->` and
+`<!-- litfamily:litopencode:end -->` are written. The start marker also records what was added in front of the
+block, so removing it restores the original bytes under LF and CRLF alike. Writes use a temporary file and a
+rename; a second install changes nothing and makes no new backup.
+
+| Command | Effect |
+| --- | --- |
+| `install` (interactive) | Asks once, default yes; No stores `"agentFile": "off"` in `litopencode.json`. |
+| `install --yes` | Adds or refreshes the block, unless `agentFile` is `off`. |
+| `install --no-agent-file` | Leaves the file alone for that run and stores nothing. |
+| `install` (no terminal, no `--yes`) | Never adds a block; an older block is refreshed in place. |
+| `agent-file on` / `off` | Stores the setting and adds or removes the block at once. |
+| `agent-file remove` | Removes the block and, when install created the file, the file; the stored setting is untouched. |
+| `agent-file project [--dir <path>]` | Writes the project block into that folder's `AGENTS.md`, with no backup copy. |
+| `doctor` | `agentFile.state` is `present v=<x>`, `stale v=<x>`, `absent`, `off`, `malformed`, `symlink`, `not-file` or `not-utf8`. |
+
+`LITOPENCODE_AGENT_FILE=on|off` overrides the stored setting. A malformed marker pair, a symlink, a folder or a
+file that is not UTF-8 is reported as `refused-*` and left untouched. When `<root>/AGENTS.md` does not exist and
+`~/.claude/CLAUDE.md` does, nothing is created (`skipped-claude-fallback`), because OpenCode reads that Claude file
+only while its own global file is missing; `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1` lifts the guard.
+
 *OpenCode provides the event surfaces; LitOpenCode turns them into bounded routes and guards, then records the durable ledger. This is the host connection behind the commands above.*
 
 ```mermaid
@@ -370,7 +396,8 @@ There is no `uninstall` subcommand. For a global install, remove the npm binary
 npm uninstall -g @litfamily/litopencode
 ```
 
-Then remove the `@litfamily/litopencode` or `@litfamily/litopencode@<version>` entry from the `plugin` array in
+Run `litopencode agent-file remove` before that if install added the LitFamily block to the global
+`AGENTS.md`. Then remove the `@litfamily/litopencode` or `@litfamily/litopencode@<version>` entry from the `plugin` array in
 OpenCode's managed `opencode.jsonc` (or the custom root's `opencode.json`). Remove
 `~/.config/opencode/litopencode.json` only when you no longer need its user-owned routes.
 Project `.litopencode/` state is separate; preserve it for later resume or remove it only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litopencode",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "Workflow plugin for OpenCode: add lit to a prompt and the work is planned, built, checked and written down so the next session can pick it up.",
   "keywords": [
     "opencode",

package/skills/lit-adhd/SKILL.md

@@ -57,7 +57,7 @@ Use the OpenCode vocabulary for this contract: `chat.message`, `command.execute.
 | `session_id` | The id of the session that typed the request. The route prompt states it; pass it as `--session`. Without it the brief still prints but no `go` step is armed. |
 | `scope` | This worktree and the other worktrees of the same git repository. `--root <dir>` points elsewhere; `--all-dirs` is not used unless the user asks. |
 | `store` | The OpenCode session database (`opencode.db`), opened read-only, else the older JSON session store, else nothing. A missing store is said in words. |
-| `local_state` | `plans/*.md` and `.litopencode/plans/*.md` checklists, the active goal, the bounded start-work run, `.litopencode/workflow-stack/<session>.json`, `.litopencode/liveness/<session>.json`, `HANDOFF*.md` headings and the first item under their `Next` heading, and `git log`. These small records are read before the session store, so a large store cannot use up the read budget first. |
+| `local_state` | `plans/*.md` and `.litopencode/plans/*.md` checklists, the active goal, the bounded start-work run, `.litopencode/workflow-stack/<session>.json`, `.litopencode/liveness/<session>.json`, `HANDOFF*.md` headings and the first open item under their `Next` heading (newest file first; an item marked ✅, ✓, `[x]`, `~~struck~~`, `DONE` or `SHIPPED` is skipped), and `git log`. Under `HERDR_ENV=1` it also runs `herdr agent list` once (3 s timeout; a failure reads `unknown` and counts nothing). These small records are read before the session store, so a large store cannot use up the read budget first. |
 
 ## #contract.mode_matrix
 
@@ -169,14 +169,14 @@ The collector draws `[▉▉▉░░░░░░░] 3/10` only when both numbe
 
 ### The recommended step
 
-One step, chosen in this order: something waiting on the user, a blocked session, a paused discipline, another running session (with what it is doing now), the running start-work run, the single open plan, the first item under this worktree's `HANDOFF.md` `Next` heading (it never runs on `go`), the newest unfinished session, an open plan in another worktree, the most recent session that stopped. The box always names a real step from the records; only an empty window asks what to start. If the step belongs to this session and is one of continue, keep working, or start the plan, the collector writes the next-step record and `go` follows it. If it belongs to another session or worktree, the box says where to act and `go` here only repeats that pointer; it never starts the step.
+One step, chosen in this order: something waiting on the user, a blocked session, another session's paused discipline, lanes at work (other running sessions of this worktree family, and under `HERDR_ENV=1` herdr agents working or blocked in this herdr workspace or inside the repo, never this pane; a lane seen both ways counts once), this session's own paused discipline, this session's running start-work run, another session's running start-work run (followed from that session), the single open plan, the first item under this worktree's `HANDOFF.md` `Next` heading (it never runs on `go`), the newest unfinished session, an open plan in another worktree, the most recent session that stopped. The box always names a real step from the records; only an empty window asks what to start. If the step belongs to this session and is one of continue, keep working, or start the plan, the collector writes the next-step record and `go` follows it. If it belongs to another session or worktree, the box says where to act and `go` here only repeats that pointer; it never starts the step. Lanes are counted before anything that resumes work here: while they work, this session's own paused discipline and its own run are held back, and an approval stays the one step offered. The box says to wait for them (or to answer the one waiting on the user), nothing is armed, and the closing line is ``Do not type `go` until they finish.``
 
 ## Following `go`
 
 `go` is live only while the next-step record for this session is younger than 30 minutes. It is read once and removed.
 
 - A paused discipline: the same return as `lit continue`, at the same stage and count.
-- The running start-work run: a note to keep going from the checked plan; nothing restarts.
+- The running start-work run: a note to keep going from the checked plan; nothing restarts. `go` first re-checks that the run is still active and still this session's; if not, the reply says the step no longer holds and starts nothing.
 - A single open plan: the typed start-work path, which opens a bounded run with read, write and execute under this workspace and nothing more.
 
 A pending boundary is never answered by `go`. The user types `lit approve` to grant exactly that boundary, or `lit deny`. In LitOpenCode `lit deny` ends the run, because the run lifecycle has no refused-and-still-paused state; the reply says so and says how to start it again (`start-work`, then answer the boundary differently). Forbidden actions (commit, push, publish, release, version-bump, host-config, destructive) can never become a pending boundary, so `lit approve` cannot grant them.

package/skills/lit-adhd/references/brief-format.md

@@ -17,7 +17,7 @@ The brief is Markdown, so OpenCode's chat draws it with the theme's colours.
 3. Ended sessions (done, idle) under `### ⚪ Ended · <n>` as one table, newest first, at most eight rows and an italic count of the rest. Columns: id, where (cut to 20 cells), goal (cut to 44 cells), ago (the largest unit only: `5d`, `14h`, `20m`), done (`finished`, a file count, or `·`).
 4. `### 🗺️ Roadmap`: per worktree with something to show, up to three recent commits with their month-day (`✓`), the plan step in hand (`▶ **now**`), up to two steps after it (`○ **later**`); another worktree's lines carry its name in inline code.
 5. The box, `Recommended next step`, in a code block with no language tag, so its frame keeps its columns and the chat draws it as plain text: the step wrapped at word breaks to at most three lines, then `type: go` when a step is armed.
-6. The closing line: ``Type **`go`** to do it.`` when a step is armed; otherwise `Nothing runs on its own here: open that session, or say what to do.`
+6. The closing line: ``Type **`go`** to do it.`` when a step is armed; ``Do not type `go` until they finish.`` while lanes work; otherwise `Nothing runs on its own here: open that session, or say what to do.`
 7. When the read budget ran out before every plan was read, an italic line: `<n> plans were not read (read budget used up).` Plans and the other small records are read before the session store, so this happens only with very large plan folders.
 
 ## Plans the roadmap leaves out

package/skills/lit-adhd/references/status-taxonomy.md

@@ -31,4 +31,4 @@ A `done` card never names a next step: what it left open is history. An `alive`
 
 ## Recommended-step precedence
 
-Waiting, blocked, paused, another session still working, the running start-work run (this session only), the single open plan, this worktree's `HANDOFF.md` `Next` item, the newest idle session with a known next step. The next-step record is written only for `continue`, `work` and `plan`, and only when the step belongs to the asking session; a `HANDOFF.md` item writes no record at all.
+Waiting, blocked, another session's paused discipline, lanes at work (other working sessions plus herdr agents under `HERDR_ENV=1`, counted once each; no record), this session's own paused discipline, the running start-work run (this session only), another session's running run (a pointer there), the single open plan, this worktree's newest `HANDOFF*.md` first open `Next` item, the newest idle session with a known next step. The next-step record is written only for `continue`, `work` and `plan`, and only when the step belongs to the asking session; a `HANDOFF.md` item writes no record at all.

package/skills/lit-adhd/scripts/rewind.mjs

@@ -265,7 +265,10 @@ function goalOf(raw) {
   };
 }
 
-// The first list item or line of text under a `Next` or `Next Steps` heading, without its marker.
+// An item someone already marked finished; the words are matched case-sensitively, so "done" in prose stays open.
+const HANDOFF_DONE = /✅|✓|^\[[xX]\]|~~.+~~|\b(?:DONE|SHIPPED)\b/u;
+
+// The first open list item or line of text under a `Next` or `Next Steps` heading, without its marker.
 function handoffNextOf(text) {
   const lines = text.split(/\r?\n/u);
   const start = lines.findIndex((line) => /^#{1,6}\s+Next(?:\s+Steps)?\s*$/iu.test(line.trim()));
@@ -273,7 +276,7 @@ function handoffNextOf(text) {
   for (const line of lines.slice(start + 1)) {
     if (/^#{1,6}\s/u.test(line.trim())) return undefined;
     const item = line.trim().replace(/^(?:[-*+]|\d+[.)])\s+/u, "");
-    if (item !== "") return item;
+    if (item !== "" && !HANDOFF_DONE.test(item)) return item;
   }
   return undefined;
 }
@@ -324,7 +327,7 @@ export function readLocalState(dir) {
       const record = readJson(join(livenessDir, name), 1024);
       const atMs = isRecord(record) ? Date.parse(str(record.at)) : Number.NaN;
       if (isRecord(record) && SAFE_SESSION.test(str(record.sessionId)) && ["alive", "idle", "ended"].includes(record.state) && Number.isFinite(atMs)) {
-        state.liveness.set(record.sessionId, { state: record.state, atMs });
+        state.liveness.set(record.sessionId, { state: record.state, atMs, pane: typeof record.herdrPane === "string" ? clean(record.herdrPane, 32) : undefined });
       }
     }
   } catch {
@@ -339,8 +342,17 @@ export function readLocalState(dir) {
   } catch {
     // no stacks recorded for this worktree
   }
+  // The newest handoff file first: a lane's fresh HANDOFF beats an old root one.
   try {
-    for (const name of readdirSync(dir).filter((entry) => /^HANDOFF.*\.md$/u.test(entry)).slice(0, 3)) {
+    const changed = (name) => {
+      try {
+        return lstatSync(join(dir, name)).mtimeMs;
+      } catch {
+        return 0;
+      }
+    };
+    const names = readdirSync(dir).filter((entry) => /^HANDOFF.*\.md$/u.test(entry)).slice(0, 40);
+    for (const name of names.map((entry) => [entry, changed(entry)]).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([entry]) => entry)) {
       const text = readSmall(join(dir, name), FILE_CAP);
       if (text === undefined) continue;
       state.handoff.push(...[...text.matchAll(/^#{1,3}\s+(.+)$/gmu)].slice(0, 4).map((match) => clean(match[1], 80)));
@@ -607,6 +619,7 @@ export function buildCard({ row, detail, local, lanes, now, self = false }) {
     },
     updated: new Date(row.updated).toISOString(),
     boundary: local.work?.sessionID === row.id && local.work.boundary ? clean(local.work.boundary, 80) : undefined,
+    ...(local.liveness?.get(row.id)?.pane ? { pane: local.liveness.get(row.id).pane } : {}),
   };
 }
 
@@ -622,7 +635,37 @@ function roadmapOf(local) {
   return out;
 }
 
-export function recommend({ groups, sessionID }) {
+/**
+ * Herdr agents at work beside this session, read only under HERDR_ENV=1: working or blocked, in this
+ * herdr workspace or with a cwd inside one of `dirs`, never the asking pane. A failed, slow or malformed
+ * `herdr agent list` reads "unknown" and counts no lane.
+ */
+export function readHerdrLanes(dirs, env = process.env) {
+  if (env.HERDR_ENV !== "1") return { state: "off", agents: [] };
+  let doc;
+  try {
+    doc = JSON.parse(execFileSync("herdr", ["agent", "list"], { encoding: "utf8", timeout: 3000, env, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 1024 * 1024 }));
+  } catch {
+    return { state: "unknown", agents: [] };
+  }
+  const list = isRecord(doc) && isRecord(doc.result) && Array.isArray(doc.result.agents) ? doc.result.agents : undefined;
+  if (list === undefined) return { state: "unknown", agents: [] };
+  const inside = (cwd) => isAbsolute(str(cwd)) && dirs.some((dir) => {
+    const rel = relative(dir, resolve(str(cwd)));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+  });
+  const ownPane = str(env.HERDR_PANE_ID);
+  const workspace = str(env.HERDR_WORKSPACE_ID);
+  const agents = list
+    .filter((entry) => isRecord(entry) && (entry.agent_status === "working" || entry.agent_status === "blocked"))
+    .filter((entry) => ownPane === "" || str(entry.pane_id) !== ownPane)
+    .filter((entry) => (workspace !== "" && str(entry.workspace_id) === workspace) || inside(entry.cwd) || inside(entry.foreground_cwd))
+    .slice(0, 40)
+    .map((entry) => ({ pane: clean(str(entry.pane_id), 32), status: entry.agent_status, session: isRecord(entry.agent_session) ? str(entry.agent_session.value) : "", title: clean(str(entry.terminal_title_stripped), 60) }));
+  return { state: "read", agents };
+}
+
+export function recommend({ groups, sessionID, herdr = [] }) {
   const cards = groups.flatMap((group) => group.sessions.map((card) => ({ card, group })));
   const waiting = cards.find(({ card }) => card.status === "waits-on-you");
   if (waiting) {
@@ -631,19 +674,34 @@ export function recommend({ groups, sessionID }) {
   }
   const blocked = cards.find(({ card }) => card.status === "blocked");
   if (blocked) return { kind: "session", sessionID: blocked.card.id, text: `Open "${clip(blocked.card.goal, 50)}": its last step failed and nothing has run since.` };
-  const paused = cards.find(({ card }) => card.status === "paused");
+  // Lanes: other sessions at work here, and herdr agents beside this one; one seen both ways counts once.
+  // They are counted before anything that resumes work here: while a lane runs, this session's own paused
+  // frame and its own run are held, and only an approval (above) stays the user's call.
+  const working = cards.filter(({ card }) => card.status === "working" && card.id !== sessionID);
+  const seen = new Set(working.flatMap(({ card }) => [card.id, card.pane].filter(Boolean)));
+  const agents = herdr.filter((agent) => agent.session === "" || (agent.session !== sessionID && !seen.has(agent.session))).filter((agent) => !seen.has(agent.pane));
+  const lanes = working.length + agents.length;
+  const paused = cards.find(({ card }) => card.status === "paused" && !(lanes > 0 && card.id === sessionID));
   if (paused) {
     return paused.card.id === sessionID
       ? { kind: "continue", sessionID, text: `Return to the paused discipline in "${clip(paused.card.goal, 50)}" where it stopped.` }
       : { kind: "session", sessionID: paused.card.id, text: `Open "${clip(paused.card.goal, 50)}" and say lit continue.` };
   }
-  const working = cards.find(({ card }) => card.status === "working" && card.id !== sessionID);
-  if (working) {
-    const doing = working.card.facts.lastAction ? ` (now: ${working.card.facts.lastAction})` : "";
-    return { kind: "session", sessionID: working.card.id, text: `"${clip(working.card.goal, 50)}" in ${working.group.worktree} is still running${doing}; check on it before starting more.` };
+  if (lanes > 0) {
+    const plural = `${lanes} lane${lanes === 1 ? "" : "s"}`;
+    const waiting = agents.find((agent) => agent.status === "blocked");
+    const first = working[0];
+    const doing = first?.card.facts.lastAction ? ` (now: ${first.card.facts.lastAction})` : "";
+    const what = first ? `"${clip(first.card.goal, 50)}" in ${first.group.worktree} is still running${doing}` : `${agents[0].title || "an agent"} in pane ${agents[0].pane}`;
+    const text = waiting
+      ? `A lane waits on you: answer the one waiting on you in pane ${waiting.pane}, then wait for ${plural} to finish before starting more.`
+      : `Wait for ${plural} to finish before starting more: ${what}.`;
+    return { kind: "lanes", sessionID: first?.card.id ?? sessionID, lanes, text, short: waiting ? `answer pane ${waiting.pane}, then wait for ${plural}` : `wait for ${plural} to finish` };
   }
   const run = groups.find((group) => group.work?.status === "active");
   if (sessionID !== undefined && run?.work.sessionID === sessionID) return { kind: "work", sessionID, text: "Keep the running start-work run going from its checked plan." };
+  // Another session's active run is followed from that session, never started again here.
+  if (run) return { kind: "session", sessionID: run.work.sessionID || undefined, text: `start-work on ${run.work.plan || "its plan"} is running in another session; open that session to follow it.` };
   const here = groups.find((group) => group.current);
   const open = here?.plans.filter((plan) => plan.done < plan.total) ?? [];
   if (open.length === 1) return { kind: "plan", sessionID, target: open[0].path, text: `Start work on ${open[0].path}: ${open[0].total - open[0].done} step${open[0].total - open[0].done === 1 ? "" : "s"} left.` };
@@ -701,7 +759,8 @@ export async function collect(options = {}) {
     const legacy = openLegacy(options.storage ?? join(dataHome, "opencode", "storage"));
     store = legacy.error ? { ...store, error: `${store.error}; ${legacy.error}` } : legacy;
   }
-  const report = { schema: REWIND_SCHEMA, generatedAt: new Date(now).toISOString(), root: clean(root, 200), source: { store: store.kind ?? "none", ...(store.error ? { note: store.error } : {}) }, groups: [] };
+  const herdr = readHerdrLanes(dirs.length > 0 ? dirs : [root], options.env ?? process.env);
+  const report = { schema: REWIND_SCHEMA, generatedAt: new Date(now).toISOString(), root: clean(root, 200), source: { store: store.kind ?? "none", ...(store.error ? { note: store.error } : {}), ...(herdr.state === "off" ? {} : { herdr: herdr.state }) }, groups: [] };
   const rows = store.kind ? store.sessions(dirs, limit) : [];
   const lanes = store.kind ? store.lanes(rows.map((row) => row.id)) : new Map();
   for (const { entry, dir, local } of locals) {
@@ -728,7 +787,7 @@ export async function collect(options = {}) {
     });
   }
   report.plansSkipped = locals.reduce((total, { local }) => total + local.plansSkipped, 0);
-  report.recommended = recommend({ groups: report.groups, sessionID: options.session });
+  report.recommended = recommend({ groups: report.groups, sessionID: options.session, herdr: herdr.agents });
   const all = report.groups.flatMap((group) => group.sessions);
   const waits = all.filter((card) => card.status === "waits-on-you").length;
   report.headline = all.length === 0
@@ -740,7 +799,7 @@ export async function collect(options = {}) {
   if (options.writeNext && forThisSession && (kind === "continue" || kind === "work" || kind === "plan")) {
     const record = { kind, target: report.recommended.target ?? kind, at: now, sessionID: options.session };
     if (writeNext(root, record)) report.nextRecord = { kind, target: record.target };
-  } else if (options.writeNext && options.session !== undefined && kind !== "none" && kind !== "handoff") {
+  } else if (options.writeNext && options.session !== undefined && kind !== "none" && kind !== "handoff" && kind !== "lanes") {
     // The step belongs to another session or worktree: go here cannot run it, so it answers with where to go.
     const record = { kind: "elsewhere", target: clip(report.recommended.text, 300), at: now, sessionID: options.session };
     if (writeNext(root, record)) report.nextRecord = { kind: "elsewhere", target: record.target };
@@ -889,7 +948,7 @@ export function renderBrief(report, { ascii = false, width = 72, sessionID } = {
   for (const text of wrapCells(report.recommended.text, inner)) lines.push(`${glyph("│", "|")} ${padCells(text, inner)} ${glyph("│", "|")}`);
   if (runsHere) lines.push(`${glyph("│", "|")} ${padCells("type: go", inner)} ${glyph("│", "|")}`);
   lines.push(`${glyph("╰", "+")}${glyph("─", "-").repeat(inner + 2)}${glyph("╯", "+")}`, "```", "");
-  lines.push(runsHere ? "Type **`go`** to do it." : report.nextRecord ? "Nothing runs on its own here: open that session, or say what to do (`go` says where)." : "Nothing runs on its own here: open that session, or say what to do.");
+  lines.push(runsHere ? "Type **`go`** to do it." : report.recommended.kind === "lanes" ? "Do not type `go` until they finish." : report.nextRecord ? "Nothing runs on its own here: open that session, or say what to do (`go` says where)." : "Nothing runs on its own here: open that session, or say what to do.");
   if (report.plansSkipped > 0) lines.push("", `*${report.plansSkipped} ${report.plansSkipped === 1 ? "plan was" : "plans were"} not read (read budget used up).*`);
   return lines.join("\n");
 }

package/skills/lit-init/SKILL.md

@@ -197,6 +197,10 @@ Every lit-init run should try to prove itself wrong before completion. Pick at l
 
 If a claim cannot be verified quickly, mark it as uncertain or omit it. Future agents are better served by a small verified map than a large speculative one.
 
+## LitFamily Project Block
+
+When the user has approved writing the root `AGENTS.md`, the short LitFamily block can go in with `litopencode agent-file project --dir <repo root>`. It writes only the lines between its own `litfamily:litopencode` markers at the end of the file, keeps every byte of the hand-written text, makes no backup copy next to tracked files, and reports `unchanged` on a repeat. A malformed marker pair or a symlinked `AGENTS.md` is refused and reported, never rewritten. Run `litopencode agent-file project --dir <repo root> --dry-run` first when the file already exists, and treat the block as one more thing the receipt lists.
+
 ## Completion Receipt
 
 The final receipt should list files created, files updated, directories intentionally skipped, key evidence sources, tests or checks run, and cleanup. If no files were written because the run was discovery-only, say so. If local handoff or ledger state influenced the map, state that it was cross-checked. If any temp files or exploration artifacts were created, remove them or identify them as ignored evidence. Do not commit the guidance unless the user explicitly asks for a commit.