@litfamily/litopencode 1.0.25 → 1.0.27

package/CHANGELOG.md

@@ -5,6 +5,20 @@ are tracked separately from this product history.
 
 ## Unreleased
 
+## 1.0.27 - 2026-10-18
+
+- When a startup update fails and the rollback leaves the old setup working, OpenCode no longer reruns the snapshot and npm install on every start. Startup leaves that same version alone for a day; an explicit install still runs it, and a newer release is tried at once. The receipt names the failed step, a timeout or a missing command, without command output. `litopencode doctor` now reports the update state, its cause, what the next start will run ("installed X, running Y") and a remedy for each cause, and says it cannot see inside a running OpenCode.
+
+- The optional Jev skill hint is gone. In testing it improved skill choice by no more than run-to-run noise, and in real use the model followed none of the 45 hints it received. LitOpenCode no longer contacts TypeSafe, adds no hint line or toast, and `litopencode doctor` no longer reports it. `LITOPENCODE_JEV`, the other `LITOPENCODE_JEV_*` variables and `TYPESAFE_API_KEY` are now ignored and can be deleted, and so can an old debug trace at `.litopencode/logs/jev-skill-hint.jsonl`.
+
+- lit-loop now loads the skill that matches a request before it inspects the workspace; plain questions and requests no listed skill covers still load none. The review-work trigger now names reviewing a patch, diff, PR or open changes, with Korean cues, and the workflow-loop trigger names carrying one feature, fix or ticket through build, tests, real-surface checks and cleanup.
+
+- A request whose deliverable is a Markdown or plain-text file, such as `report.md` or `slides.md`, now gets ordinary Markdown. lit-docx and lit-pptx no longer write their converter source (YAML front matter and `:::` blocks) into those files or start a DOCX or PPTX build; they keep that source format only for files they render.
+
+## 1.0.26 - 2026-10-16
+
+- The write guard now refuses more of the lines that tell a reader what a document is not for, such as `This table is not a ranking.` or `이 문서는 제품을 비교하려는 것이 아닙니다.` These forms came from real sessions. Bold-label callouts such as `> **주의:** ...` are now read too, while ordinary quoted text is still skipped, and lines from manuals and lab reports that only look similar stay allowed. Files saved through `apply_patch` are now checked before they land, the same way the write and edit tools already were.
+
 ## 1.0.25 - 2026-10-15
 
 - The write guard now refuses sentences that say what a document is not for, such as `동일 조건의 독립 성능 비교로 쓰지 않음.` or an English line saying a result is not a benchmark. When the model writes one with the write or edit tool, the call is refused and the model rewrites it. Three new rules cover Korean pledges, a Korean pledge repeated through a document, and the English forms, and the status-negation warning now also reads `쓰지 않음`, the polite endings and bold-wrapped endings. Legal and financial notices, safety warnings, operating rules, method lines and real negative findings stay untouched, and the rules still finish in milliseconds on very long runs of spaces. The lit-docx and lit-pptx skills now ask for a real limit once, as a fact beside the number it affects, and keep anything about what the document is not for in the reply.

package/README-Ko-KR.md

@@ -1,13 +1,13 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitOpenCode 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitOpenCode 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 # LitOpenCode
 
 **LitOpenCode는 OpenCode용 워크플로 플러그인입니다. 프롬프트에 `lit`만 붙이면 계획하고, 만들고, 확인하고, 기록까지 남겨서 다음 세션이 어디서 멈췄는지 바로 압니다.**
 
 <p align="center">
-<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/readme/badge-version.svg" alt="1.0.25" /></a>
+<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/readme/badge-version.svg" alt="1.0.27" /></a>
 <a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://img.shields.io/npm/dm/@litfamily/litopencode?label=downloads&color=D7F75B" alt="월간 npm 다운로드 수" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
 <a href="https://github.com/wjgoarxiv/litopencode"><img src="https://img.shields.io/github/stars/wjgoarxiv/litopencode?style=social" alt="GitHub 스타" /></a>
 </p>
 
@@ -57,9 +57,9 @@ npm uninstall -g @litfamily/litopencode
 ## 더 보기
 
 - [GitHub의 사용 안내](https://github.com/wjgoarxiv/litopencode/blob/main/docs/guide-Ko-KR.md): 설치 옵션, 자동 인수인계, 문제 해결, 제거
-- [워크플로 상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/reference-Ko-KR.md) · [English reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/reference.md)
-- [마이그레이션 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/CHANGELOG.md) · [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/privacy.md)
-- [LitFamily 허브](https://github.com/wjgoarxiv/litfamily) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/LICENSE) · [ASCII 글꼴 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/readme/JetBrainsMono-OFL.txt)
+- [워크플로 상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/reference-Ko-KR.md) · [English reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/reference.md)
+- [마이그레이션 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/CHANGELOG.md) · [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/privacy.md)
+- [LitFamily 허브](https://github.com/wjgoarxiv/litfamily) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/LICENSE) · [ASCII 글꼴 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/readme/JetBrainsMono-OFL.txt)
 
 <details>
 <summary>ASCII 로고 복사</summary>

package/README.md

@@ -1,13 +1,13 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitOpenCode robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitOpenCode robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 # LitOpenCode
 
 **LitOpenCode is a workflow plugin for OpenCode. Add `lit` to a prompt and the work gets planned, built, checked and written down, so the next session knows where you stopped.**
 
 <p align="center">
-<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/readme/badge-version.svg" alt="1.0.25" /></a>
+<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/readme/badge-version.svg" alt="1.0.27" /></a>
 <a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://img.shields.io/npm/dm/@litfamily/litopencode?label=downloads&color=D7F75B" alt="npm downloads per month" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 <a href="https://github.com/wjgoarxiv/litopencode"><img src="https://img.shields.io/github/stars/wjgoarxiv/litopencode?style=social" alt="GitHub stars" /></a>
 </p>
 
@@ -57,9 +57,9 @@ npm uninstall -g @litfamily/litopencode
 ## More
 
 - [Guide on GitHub](https://github.com/wjgoarxiv/litopencode/blob/main/docs/guide.md): install options, automatic handoff, troubleshooting and removal.
-- [Workflow reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/reference.md)
-- [Migration notes](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/CHANGELOG.md) · [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/privacy.md)
-- [LitFamily hub](https://github.com/wjgoarxiv/litfamily) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/LICENSE) · [ASCII font license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.25/docs/assets/readme/JetBrainsMono-OFL.txt)
+- [Workflow reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/reference.md)
+- [Migration notes](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/CHANGELOG.md) · [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/privacy.md)
+- [LitFamily hub](https://github.com/wjgoarxiv/litfamily) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/LICENSE) · [ASCII font license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.27/docs/assets/readme/JetBrainsMono-OFL.txt)
 
 <details>
 <summary>Copy ASCII logo</summary>

package/dist/activation-routing.js

@@ -67,6 +67,11 @@ const diagramCreationIntent = /^\s*(?:lit[,:]?\s+)?(?:please\s+)?(?:create|draw|
 const officeAuthoringVerb = /(?<![a-z])(?:make|create|write|draft|prepare|produce|generate|convert|edit|build)(?![a-z])|(?<![a-z])turn(?=(?:[^.!?\n]|\.(?=\S))*?(?<![a-z])into(?![a-z])(?:[^.!?\n]|\.(?=\S))*?(?<![a-z])(?:slides?|decks?|presentations?|pptx?|reports?|documents?|docx|word)(?![a-z]))|만들|작성|써줘|제작|변환|편집/u;
 const reportNoun = /(?<![a-z])(?:reports?|documents?|docx|word)(?![a-z])|보고서|리포트|기획서|제안서|문서|워드/u;
 const slidesNoun = /(?<![a-z])(?:slides?|decks?|presentations?|pptx?)(?![a-z])|발표자료|발표|슬라이드|피피티|덱/u;
+// A deliverable the user asked to receive as Markdown or plain text ("saved as report.md", "in Markdown",
+// "as plain text"). An input file such as "turn notes.md into slides" is not one. A named Office or PDF
+// output keeps the skill route, because the skill then renders that file from its own source.
+const markdownDeliverable = /(?<![a-z])(?:save|saved|saving|write|written|output|deliver|export)\s+(?:(?:it|them|this|both|each)\s+)?(?:as|to|in|into)\s+`?[\w./-]*\.(?:md|markdown|txt)(?![a-z])|(?<![a-z])(?:as|in)\s+(?:plain\s+)?markdown(?![a-z])|(?<![a-z])plain[- ]text(?![a-z])|마크다운(?:으로|\s*파일로|\s*형식)|\.md\s*(?:로|으로|파일로)\s*(?:저장|작성)/u;
+const officeFileFormat = /(?<![a-z])(?:docx|pptx?|pdf|word|powerpoint)(?![a-z])|워드|파워포인트|피피티/u;
 // lit-typographic-motion (MO-C-18..24). The trigger is a creation verb plus a compound motion-video
 // noun, or plus a bare video noun that none of the five exclusions claims. Bare 모션/motion and
 // 인트로/intro never trigger alone. The verbs are the office/UI making verbs plus a small motion set
@@ -378,7 +383,12 @@ export function promptForChatActivationMode(mode, triggerText = "") {
 After the workspace check, use OpenCode's native skill tool to load lit-diagram-drawer before authoring the requested conceptual diagram. This is the one narrowly relevant skill for this bounded task. Resolve resources from the skill location returned by OpenCode, follow its verification and export steps, and inspect the final PNG. If the skill is unavailable, report that limit instead of claiming it ran.
 </lit-task-mode>`);
     }
-    if (mode === "lit-task" && officeAuthoringVerb.test(raw)) {
+    if (mode === "lit-task" && officeAuthoringVerb.test(raw) && markdownDeliverable.test(raw) && !officeFileFormat.test(raw) && (reportNoun.test(raw) || slidesNoun.test(raw))) {
+        targetedPrompt = targetedPrompt.replace("</lit-task-mode>", `
+The requested deliverable is a Markdown or plain-text file, not an Office file. Write each named file as ordinary Markdown that a reader opens directly: headings, paragraphs, lists and tables, with no YAML front matter, no \`:::\` directive blocks and no tonality, layout or title-treatment keys. Do not build a DOCX or PPTX and do not load lit-docx or lit-pptx for it; their Markdown is converter source and belongs only beside a file that skill renders.
+</lit-task-mode>`);
+    }
+    else if (mode === "lit-task" && officeAuthoringVerb.test(raw)) {
         const skills = [reportNoun.test(raw) ? "lit-docx" : undefined, slidesNoun.test(raw) ? "lit-pptx" : undefined].filter(Boolean);
         if (skills.length > 0)
             targetedPrompt = targetedPrompt.replace("</lit-task-mode>", `

package/dist/activation.d.ts

@@ -2,7 +2,6 @@ import type { Hooks, PluginInput } from "@opencode-ai/plugin";
 import type { SessionLookup } from "./session-lineage.ts";
 import type { BoundedAuthorityOptions } from "./bounded-authority.ts";
 import { type AutoHandoffRouteMode } from "./auto-handoff.ts";
-import { type JevSkillHintPart } from "./jev-skill-hint.ts";
 export { litHandoffPromptInjection, scientificVisualizationPromptInjection } from "./activation-managed-prompts.ts";
 export { litActivationBanner } from "./activation-prompt-utils.ts";
 export { litLoopPromptInjection, litPlanPromptInjection } from "./activation-primary-prompts.ts";
@@ -11,12 +10,6 @@ export { comprehendPromptInjection, debuggingPromptInjection, deepInterviewPromp
 type ChatMessageHook = NonNullable<Hooks["chat.message"]>;
 type ActivationToastClient = Pick<PluginInput["client"], "tui">;
 export declare function showActivationToast(client: ActivationToastClient | undefined, skillId: string, env?: NodeJS.ProcessEnv): void;
-/**
- * One quiet `info` toast per hinted turn; notes, `none` and silent turns never reach it. On the first
- * eligible turn of a session (`announce`) the standout ON notice goes out instead, with that turn's hint
- * as its body: the TUI keeps a single toast, so a second one would replace the notice at once.
- */
-export declare function showJevSkillHintToast(client: ActivationToastClient | undefined, hint: JevSkillHintPart | undefined, announce?: boolean): void;
 export type ChatMessageActivationOptions = {
     readonly getSession?: SessionLookup;
     readonly hostArgv?: readonly string[];
@@ -30,8 +23,5 @@ export type ChatMessageActivationOptions = {
     readonly trustedInjectedSkill?: (sessionID: string) => string | undefined;
     /** Restores that skill after the root-turn reset; the command already showed its activation toast. */
     readonly onTrustedSkillResume?: (sessionID: string, skillId: string) => void | Promise<void>;
-    /** Consumes the mark `command.execute.before` left for this session's next message. */
-    readonly isCommandTurn?: (sessionID: string) => boolean;
-    readonly skillHint?: (sessionID: string, promptText: string) => Promise<JevSkillHintPart | undefined>;
 };
 export declare function createChatMessageActivationHook(projectRoot: string, options?: ChatMessageActivationOptions): ChatMessageHook;

package/dist/activation.js

@@ -8,7 +8,6 @@ import { isReadOnlyWorkflowFamilyPlan } from "./workflow-families.js";
 import { queryKnowledge } from "./knowledge.js";
 import { activationDiscipline } from "./activation-probe.js";
 import { micro, supportsMarkGlyphs } from "./lit-mark.js";
-import { jevSkillHintAwarenessText, jevSkillHintToastText } from "./jev-skill-hint.js";
 // Prompt modules preserve minimum-first, single-task or few-task planning, avoidable custom code review,
 // and external-source safety; this module only coordinates their unchanged activation surfaces.
 export { litHandoffPromptInjection, scientificVisualizationPromptInjection } from "./activation-managed-prompts.js";
@@ -35,32 +34,6 @@ export function showActivationToast(client, skillId, env = process.env) {
         // The activation prompt is the primary surface; this toast is best-effort UI feedback.
     }
 }
-/**
- * One quiet `info` toast per hinted turn; notes, `none` and silent turns never reach it. On the first
- * eligible turn of a session (`announce`) the standout ON notice goes out instead, with that turn's hint
- * as its body: the TUI keeps a single toast, so a second one would replace the notice at once.
- */
-export function showJevSkillHintToast(client, hint, announce = false) {
-    const hinted = hint?.kind === "hint" ? jevSkillHintToastText(hint.skillId, hint.latencyMs) : undefined;
-    let body;
-    if (announce) {
-        body = hinted === undefined
-            ? { message: jevSkillHintAwarenessText, variant: "warning" }
-            : { title: jevSkillHintAwarenessText, message: hinted, variant: "warning" };
-    }
-    else if (hinted !== undefined) {
-        body = { message: hinted, variant: "info" };
-    }
-    else {
-        return;
-    }
-    try {
-        const pending = client?.tui?.showToast({ body });
-        void pending?.catch(() => undefined);
-    }
-    catch { // no-excuse-ok: catch -- a missing or failing TUI must never block the user message.
-    }
-}
 const knownSubagentAgentNames = new Set([
     ...litOpenCodeAgents.filter((agent) => agent.mode !== "primary").map((agent) => agent.id),
     "build",
@@ -92,9 +65,6 @@ export function createChatMessageActivationHook(projectRoot, options = {}) {
         if (processedOutputs.has(output))
             return;
         processedOutputs.add(output);
-        // Command marks are keyed by session and consumed here, on every turn: the host hands this hook a
-        // new parts array, so the array `command.execute.before` saw can never be matched by identity.
-        const commandTurn = options.isCommandTurn?.(input.sessionID) === true;
         const trustedInjectedSkill = options.trustedInjectedSkill?.(input.sessionID);
         const agent = input.agent ?? (typeof output.message.agent === "string" ? output.message.agent : undefined);
         const childSession = await isChildSessionMessage(input.sessionID, agent, options.getSession);
@@ -161,30 +131,6 @@ export function createChatMessageActivationHook(projectRoot, options = {}) {
                 // A malformed or unreadable knowledge store stays silent instead of inventing context.
             }
         }
-        // The optional skill hint only speaks on root turns that no command or deterministic route claimed.
-        if (!childSession && mode === undefined && options.skillHint !== undefined && !commandTurn) {
-            const promptText = nonEmptyTextParts
-                .filter((part) => part.synthetic !== true)
-                .map((part) => part.text)
-                .join("\n");
-            try {
-                const hint = await options.skillHint(input.sessionID, promptText);
-                if (hint !== undefined) {
-                    output.parts.push({
-                        id: `prt_litopencode_skill_hint_${idSuffix(input.messageID ?? output.message.id)}`,
-                        sessionID: input.sessionID,
-                        messageID: input.messageID ?? output.message.id,
-                        type: "text",
-                        text: hint.text,
-                        // Sent to the model like any text part, but not shown or copied as the user's own words.
-                        synthetic: true,
-                        metadata: { litopencodeSkillHint: { kind: hint.kind, source: "chat.message" } }
-                    });
-                }
-            }
-            catch { // no-excuse-ok: catch -- the optional hint must never block the user message.
-            }
-        }
         if (mode === undefined || childSession)
             return;
         const trigger = mode === "lit-handoff" ? "handoff" : mode === "lit-scientific-visualization" ? mode : "lit";

package/dist/agents/defaults.js

@@ -64,7 +64,8 @@ const litLoopPrompt = [
     interfaceWorkHandoff,
     "Do not call the task, lit, litwork, start-work, or review-work tools, and do not delegate for that path.",
     "Do not create a TODO plan, durable goal or ledger, or evidence tree. Do not preload the workflow skills or agent roster. The activation hook has already handled bare lit.",
-    "Do not load skill documentation before inspecting the task and repository. Use the supplied acceptance criteria directly; consult at most one narrowly relevant skill only if inspection reveals a specific gap it can resolve.",
+    "On that bounded path, use the supplied acceptance criteria directly; consult at most one narrowly relevant skill only if inspection reveals a specific gap it can resolve.",
+    "Otherwise, when the request matches a skill in the available skills list, load that skill with the skill tool first, then inspect the workspace under its guidance. Plain questions, explanations, and requests no listed skill covers need no skill.",
     "Use the durable loop only when the user explicitly asks for tracked multi-turn work, or the task genuinely needs resumption across turns or independent workstreams.",
     "For a long workflow, delegate only independent slices that materially reduce work. Treat at most 20 concurrent subagents as an advisory ceiling; OpenCode exposes no verified numeric hard limit, so never claim host enforcement.",
     "When delegation is used, require each worker DoneClaim to name changed files, exact tests, real-surface evidence, risks, and a cleanup receipt. An independent verifier must confirm it before the slice becomes FullyDone.",

package/dist/cli/auto-update.d.ts

@@ -6,6 +6,8 @@ export declare const autoUpdateLockTimeoutMs = 2000;
 /** Keep a live owner protected for the whole bounded transaction plus one command window. */
 export declare const autoUpdateInstallLockStaleMs: number;
 export declare const autoUpdateRecursionEnv = "LITOPENCODE_AUTO_UPDATE_IN_PROGRESS";
+/** After a safe rollback, OpenCode starts leave the same target alone for this long. */
+export declare const autoUpdateFailureBackoffMs: number;
 type CommandOutput = {
     readonly stdout?: string;
     readonly stderr?: string;
@@ -62,6 +64,11 @@ type DoctorReceipt = {
     };
     readonly error?: string;
 };
+export type AutoUpdateFailure = {
+    readonly step: "prepare" | "npm-install" | "install" | "doctor";
+    readonly timedOut: boolean;
+    readonly missingCommand: boolean;
+};
 type AutoUpdateReceipt = {
     readonly schemaVersion: 1;
     readonly status: AutoUpdateRunResult["status"];
@@ -82,6 +89,7 @@ type AutoUpdateReceipt = {
         readonly ok: boolean;
         readonly error?: string;
     };
+    readonly failure?: AutoUpdateFailure;
 };
 /**
  * The staged CLI needs Node. Inside OpenCode the plugin runs on a Bun-compiled
@@ -92,6 +100,7 @@ export declare function childNodeExecutable(execPath?: string, versions?: NodeJS
 export declare function autoUpdateInstallLockPath(homeDir?: string): string;
 export declare function autoUpdateJournalPath(homeDir?: string): string;
 export declare function autoUpdateReceiptPath(homeDir?: string): string;
+export declare function autoUpdateCheckPath(homeDir?: string): string;
 export declare function isAutoUpdateDisabled(env?: NodeJS.ProcessEnv, argv?: readonly string[]): boolean;
 export declare function shouldRunInteractiveAutoUpdate(input: InteractiveAutoUpdateGate): boolean;
 /**
@@ -115,11 +124,28 @@ export type AutoUpdateReceiptSummary = {
     readonly stagedStateKnown: boolean;
     readonly rollbackOk: boolean;
     readonly finishedAt: number;
+    readonly currentVersion?: string;
+    readonly targetVersion?: string;
+    readonly failure?: AutoUpdateFailure;
 };
 /** Read only the bounded safety summary used by doctor; never echo command output. */
 export declare function readAutoUpdateReceipt(homeDir?: string): Promise<AutoUpdateReceiptSummary | {
     readonly status: "unreadable";
 } | undefined>;
-export declare function runPluginAutoUpdate(): Promise<AutoUpdateRunResult>;
+export type AutoUpdateCheckRecord = {
+    readonly schemaVersion: 1;
+    readonly at: number;
+    /** The plugin version this OpenCode start loaded, which keeps running until the next start. */
+    readonly runningVersion: string;
+    readonly status: AutoUpdateRunResult["status"];
+    readonly reason?: string;
+    readonly targetVersion?: string;
+};
+/** Best effort: a state root that is not safe to write never stops the plugin. */
+export declare function recordAutoUpdateCheck(homeDir: string, runningVersion: string, result: AutoUpdateRunResult): Promise<void>;
+export declare function readAutoUpdateCheck(homeDir?: string): Promise<AutoUpdateCheckRecord | undefined>;
+export declare function runPluginAutoUpdate(options?: {
+    readonly homeDir?: string;
+}): Promise<AutoUpdateRunResult>;
 export declare function runInteractiveAutoUpdate(input: InteractiveAutoUpdateGate): Promise<AutoUpdateRunResult>;
 export {};

package/dist/cli/auto-update.js

@@ -15,10 +15,13 @@ export const autoUpdateLockTimeoutMs = 2_000;
 /** Keep a live owner protected for the whole bounded transaction plus one command window. */
 export const autoUpdateInstallLockStaleMs = autoUpdateTransactionBoundMs + autoUpdateTimeoutMs;
 export const autoUpdateRecursionEnv = "LITOPENCODE_AUTO_UPDATE_IN_PROGRESS";
+/** After a safe rollback, OpenCode starts leave the same target alone for this long. */
+export const autoUpdateFailureBackoffMs = 24 * 60 * 60 * 1000;
 const stateRootName = ".litopencode";
 const receiptFileName = "auto-update-receipt.json";
 const journalFileName = "auto-update-journal.jsonl";
 const installLockFileName = "auto-update-install.lock";
+const checkFileName = "auto-update-check.json";
 const maxCommandOutputBytes = 4 * 1024 * 1024;
 const execFileAsync = promisify(execFile);
 /**
@@ -43,6 +46,9 @@ export function autoUpdateJournalPath(homeDir = os.homedir()) {
 export function autoUpdateReceiptPath(homeDir = os.homedir()) {
     return path.join(stateRoot(homeDir), receiptFileName);
 }
+export function autoUpdateCheckPath(homeDir = os.homedir()) {
+    return path.join(stateRoot(homeDir), checkFileName);
+}
 function truthyEnvironmentValue(value) {
     return value !== undefined;
 }
@@ -110,6 +116,16 @@ function commandFailure(error) {
         .filter(Boolean)
         .join("; ");
 }
+/** Classify a failure by kind only; command output never reaches the receipt. */
+function failureKind(step, error) {
+    const candidate = (typeof error === "object" && error !== null ? error : {});
+    const message = typeof candidate.message === "string" ? candidate.message : "";
+    return {
+        step,
+        timedOut: candidate.killed === true || /automatic update command exceeded/u.test(message),
+        missingCommand: candidate.code === "ENOENT"
+    };
+}
 async function defaultRunCommand(command, args, options) {
     return await execFileAsync(command, [...args], options);
 }
@@ -400,6 +416,8 @@ async function updateTransaction(options, homeDir, currentVersion, targetVersion
     // resulting host state unknown until the snapshot is restored and verified.
     let stagedStateKnown = true;
     let priorStateVerified = false;
+    let step = "prepare";
+    let failure;
     try {
         await fs.mkdir(stageRoot, { recursive: true, mode: 0o700 });
         await fs.writeFile(path.join(stageRoot, "package.json"), '{"private":true}\n', { encoding: "utf8", mode: 0o600 });
@@ -423,16 +441,19 @@ async function updateTransaction(options, homeDir, currentVersion, targetVersion
             "--no-save",
             spec
         ];
+        step = "npm-install";
         await bounded(() => runCommand("npm", npmArgs, { cwd: stageRoot, env: childEnv, timeout: autoUpdateTimeoutMs, maxBuffer: maxCommandOutputBytes }), autoUpdateTimeoutMs);
         await appendJournal(homeDir, "npm-install", { spec });
         const entrypoint = await packageEntrypoint(stageRoot, targetVersion);
         const nodeExecutable = options.nodeExecutable ?? childNodeExecutable();
         const installArgs = [entrypoint, "install", "--root", options.configRoot, "--no-model-prompt", "--no-permission-prompt", "--no-auto-update"];
+        step = "install";
         stagedStateKnown = false;
         await bounded(() => runCommand(nodeExecutable, installArgs, { cwd: options.configRoot, env: childEnv, timeout: autoUpdateTimeoutMs, maxBuffer: maxCommandOutputBytes }), autoUpdateTimeoutMs);
         stagedStateKnown = true;
         await appendJournal(homeDir, "install", { spec });
         const doctorArgs = [entrypoint, "doctor", "--root", options.configRoot, "--json", "--no-auto-update"];
+        step = "doctor";
         stagedStateKnown = false;
         const doctorOutput = await bounded(() => runCommand(nodeExecutable, doctorArgs, { cwd: options.configRoot, env: childEnv, timeout: autoUpdateTimeoutMs, maxBuffer: maxCommandOutputBytes }), autoUpdateTimeoutMs);
         doctor = parseDoctorOutput(doctorOutput, targetVersion);
@@ -444,8 +465,8 @@ async function updateTransaction(options, homeDir, currentVersion, targetVersion
         await appendJournal(homeDir, "updated", { spec });
     }
     catch (error) {
-        const failure = commandFailure(error);
-        await tryAppendJournal(homeDir, "failure", { error: failure });
+        failure = failureKind(step, error);
+        await tryAppendJournal(homeDir, "failure", { error: commandFailure(error) });
         try {
             await restoreSnapshot(options.configRoot, snapshot);
             priorStateVerified = await verifySnapshot(options.configRoot, snapshot);
@@ -482,7 +503,8 @@ async function updateTransaction(options, homeDir, currentVersion, targetVersion
         priorStateVerified: status === "updated" ? true : priorStateVerified,
         stagedStateKnown,
         doctor,
-        rollback
+        rollback,
+        ...(failure === undefined ? {} : { failure })
     };
     await writeReceipt(homeDir, receipt);
     return {
@@ -497,6 +519,20 @@ async function updateTransaction(options, homeDir, currentVersion, targetVersion
         ...(status === "rolled-back" || status === "failed" ? { rollback } : {})
     };
 }
+/**
+ * A rollback that left the old setup proven in place is safe to wait on. Without
+ * this, a failing update re-ran its snapshot and npm install on every OpenCode
+ * start. Anything less certain keeps retrying, because a retry is the repair path.
+ */
+async function inFailureBackoff(homeDir, targetVersion) {
+    const last = await readAutoUpdateReceipt(homeDir);
+    if (last === undefined || last.status !== "rolled-back")
+        return false;
+    if (!last.rollbackOk || !last.priorStateVerified || !last.stagedStateKnown || last.targetVersion !== targetVersion)
+        return false;
+    const age = Date.now() - last.finishedAt;
+    return age >= 0 && age < autoUpdateFailureBackoffMs;
+}
 export async function runAutoUpdate(options) {
     const env = options.env ?? process.env;
     if (isAutoUpdateDisabled(env, options.argv))
@@ -517,6 +553,9 @@ export async function runAutoUpdate(options) {
     const comparison = compareStableVersions(targetVersion, options.currentVersion);
     if (comparison !== 1)
         return { status: "skipped", currentVersion: options.currentVersion, targetVersion, reason: "up-to-date" };
+    if (options.reason === "plugin" && (await inFailureBackoff(homeDir, targetVersion))) {
+        return { status: "skipped", currentVersion: options.currentVersion, targetVersion, reason: "backoff" };
+    }
     let lock;
     try {
         lock = await acquireInstallLock(homeDir);
@@ -551,6 +590,14 @@ export function autoUpdateDiagnostic(result) {
     const backup = result.backupPath === undefined ? "" : ` Retained backup: ${result.backupPath}.`;
     return `Automatic update stopped without claiming success (${result.status}). Inspect the receipt at ${receipt}.${backup}`;
 }
+function isFailureRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return ((record.step === "prepare" || record.step === "npm-install" || record.step === "install" || record.step === "doctor") &&
+        typeof record.timedOut === "boolean" &&
+        typeof record.missingCommand === "boolean");
+}
 /** Read only the bounded safety summary used by doctor; never echo command output. */
 export async function readAutoUpdateReceipt(homeDir = os.homedir()) {
     const receiptPath = autoUpdateReceiptPath(homeDir);
@@ -580,7 +627,10 @@ export async function readAutoUpdateReceipt(homeDir = os.homedir()) {
             priorStateVerified: parsed.priorStateVerified,
             stagedStateKnown: parsed.stagedStateKnown,
             rollbackOk: parsed.rollback.ok,
-            finishedAt: parsed.finishedAt
+            finishedAt: parsed.finishedAt,
+            ...(typeof parsed.currentVersion === "string" ? { currentVersion: parsed.currentVersion } : {}),
+            ...(typeof parsed.targetVersion === "string" ? { targetVersion: parsed.targetVersion } : {}),
+            ...(isFailureRecord(parsed.failure) ? { failure: { step: parsed.failure.step, timedOut: parsed.failure.timedOut, missingCommand: parsed.failure.missingCommand } } : {})
         };
     }
     catch (error) {
@@ -598,16 +648,65 @@ async function isLocalCheckout(packageRoot) {
         return false;
     }
 }
-export async function runPluginAutoUpdate() {
+/** Best effort: a state root that is not safe to write never stops the plugin. */
+export async function recordAutoUpdateCheck(homeDir, runningVersion, result) {
+    try {
+        await ensurePrivateStateRoot(homeDir);
+        const record = {
+            schemaVersion: 1,
+            at: Date.now(),
+            runningVersion,
+            status: result.status,
+            ...(result.reason === undefined ? {} : { reason: result.reason }),
+            ...(result.targetVersion === undefined ? {} : { targetVersion: result.targetVersion })
+        };
+        const checkPath = autoUpdateCheckPath(homeDir);
+        const temporary = `${checkPath}.${randomUUID()}.tmp`;
+        await fs.writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+        await fs.rename(temporary, checkPath);
+    }
+    catch {
+        // The record only feeds doctor.
+    }
+}
+export async function readAutoUpdateCheck(homeDir = os.homedir()) {
+    try {
+        const checkPath = autoUpdateCheckPath(homeDir);
+        const stat = await fs.lstat(checkPath);
+        if (stat.isSymbolicLink() || !stat.isFile() || (stat.mode & 0o077) !== 0)
+            return undefined;
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            return undefined;
+        const parsed = JSON.parse(await fs.readFile(checkPath, "utf8"));
+        if (parsed.schemaVersion !== 1 || typeof parsed.at !== "number" || typeof parsed.runningVersion !== "string" || typeof parsed.status !== "string")
+            return undefined;
+        return {
+            schemaVersion: 1,
+            at: parsed.at,
+            runningVersion: parsed.runningVersion,
+            status: parsed.status,
+            ...(typeof parsed.reason === "string" ? { reason: parsed.reason } : {}),
+            ...(typeof parsed.targetVersion === "string" ? { targetVersion: parsed.targetVersion } : {})
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function runPluginAutoUpdate(options = {}) {
     const metadata = await readPackageMetadata();
-    if (await isLocalCheckout(metadata.packageRoot))
-        return { status: "skipped", reason: "local-checkout" };
-    return await runAutoUpdate({
-        reason: "plugin",
-        configRoot: defaultOpenCodeConfigRoot(),
-        currentVersion: metadata.version,
-        env: process.env
-    });
+    const homeDir = options.homeDir ?? os.homedir();
+    const result = (await isLocalCheckout(metadata.packageRoot))
+        ? { status: "skipped", reason: "local-checkout" }
+        : await runAutoUpdate({
+            reason: "plugin",
+            homeDir,
+            configRoot: defaultOpenCodeConfigRoot(),
+            currentVersion: metadata.version,
+            env: process.env
+        });
+    await recordAutoUpdateCheck(homeDir, metadata.version, result);
+    return result;
 }
 export async function runInteractiveAutoUpdate(input) {
     if (!shouldRunInteractiveAutoUpdate(input))

package/dist/cli/doctor.d.ts

@@ -1,4 +1,13 @@
 import type { CliResult } from "./types.ts";
+/**
+ * Doctor reads the receipt and the record each OpenCode start leaves behind. It
+ * cannot see inside a running OpenCode, so "running" means the last start seen.
+ */
+export declare function inspectAutoUpdate(input: {
+    readonly homeDir?: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly pinnedVersion: string | null;
+}): Promise<Record<string, unknown>>;
 /**
  * The project the plugin would use from here: OpenCode's worktree is the git root above the working
  * directory, and without one the directory itself.