@litfamily/litopencode 1.0.34 → 1.0.36

package/dist/v2/native-goal-runtime.js

@@ -0,0 +1,193 @@
+// Drives OpenCode 2's native `/goal` for lit-loop, start-work and litwork. The host has no goal setter:
+// the goal is read through the `opencode.goal` RPC and changed by sending the `/goal` command to the
+// session (`session.command`). Policy lives in native-goal.ts; this file reads the state, performs the one
+// action it returns, prints one line per change as a notice row, and records it in the ledger. Nothing here
+// throws: a failed step is recorded and the work carries on with the ledger alone.
+import { ledgerGoalDone, nativeGoalOwnership, recordNativeGoal, recordNativeGoalUnavailable } from "../native-goal-ledger.js";
+import { litOpenCodeCommands } from "../commands.js";
+import { decideNativeGoal, nativeGoalLine, nativeGoalObjective, nativeGoalRoute } from "./native-goal.js";
+/** The `opencode.goal` RPC contract as JSON Schema, so the package needs no runtime import of the host's schema library. */
+const goalDefinition = Object.freeze({
+    id: "opencode.goal",
+    methods: Object.freeze({
+        get: Object.freeze({
+            input: Object.freeze({ type: "object", properties: Object.freeze({ sessionID: Object.freeze({ type: "string" }) }), required: Object.freeze(["sessionID"]) }),
+            output: Object.freeze({})
+        })
+    }),
+    events: Object.freeze({
+        changed: Object.freeze({ schema: Object.freeze({ type: "object", properties: Object.freeze({ sessionID: Object.freeze({ type: "string" }) }), required: Object.freeze(["sessionID"]) }) })
+    })
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseGoal(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!isRecord(value) || typeof value.id !== "string" || typeof value.objective !== "string")
+        return "unreadable";
+    if (value.status !== "active" && value.status !== "paused" && value.status !== "complete")
+        return "unreadable";
+    return { id: value.id, objective: value.objective, status: value.status, ...(typeof value.reason === "string" ? { reason: value.reason } : {}) };
+}
+/** OpenCode 2.2.5 answers an RPC it does not register with type `rpc.unavailable`; any other failure is a failed read. */
+function hostLacksGoalRpc(error) {
+    return isRecord(error) && error.type === "rpc.unavailable";
+}
+function failureDetail(error) {
+    const text = error instanceof Error ? error.message : isRecord(error) ? String(error.message ?? error.type ?? "failed") : String(error);
+    return text.replace(/\s+/gu, " ").slice(0, 160);
+}
+/** A prompt the host expanded from an installed command alias file arrives as the command body, unmarked. */
+export function aliasGoalRoute(input) {
+    const text = input.trimStart();
+    for (const command of litOpenCodeCommands) {
+        const head = command.activationText.trim();
+        if (head === "" || !text.startsWith(head))
+            continue;
+        const route = nativeGoalRoute(command.id, "");
+        return route === undefined ? undefined : { route, work: text.slice(head.length) };
+    }
+    return undefined;
+}
+export function createNativeGoal(options) {
+    const { projectRoot, host } = options;
+    const client = host.rpc === undefined ? undefined : host.rpc(goalDefinition);
+    const said = new Set();
+    const running = new Set();
+    async function read(sessionID) {
+        if (client === undefined)
+            return { supported: false };
+        try {
+            return { supported: true, goal: parseGoal(await client.get({ sessionID })) };
+        }
+        catch (error) {
+            return hostLacksGoalRpc(error) ? { supported: false } : { supported: true, goal: "unreadable" };
+        }
+    }
+    async function notice(sessionID, line, key) {
+        if (line === "" || said.has(key))
+            return;
+        said.add(key);
+        try {
+            await host.session.synthetic({ sessionID, text: line, description: line, metadata: { source: "litopencode-goal" }, resume: false });
+        }
+        catch { // no-excuse-ok: catch -- a missing notice row must not stop the work; the ledger holds the record.
+            return;
+        }
+    }
+    async function fail(sessionID, route, step, error) {
+        await recordNativeGoal(projectRoot, sessionID, route, { type: "native-goal.failed", step, detail: failureDetail(error) });
+    }
+    async function perform(sessionID, route, action, goal, work) {
+        const record = goal === null || goal === "unreadable" ? undefined : goal;
+        const key = (name) => `${sessionID}:${name}:${record?.id ?? ""}:${action.kind === "report-conflict" ? action.reason : ""}`;
+        switch (action.kind) {
+            case "none":
+            case "keep":
+                return;
+            case "unavailable": {
+                if (route !== undefined)
+                    await recordNativeGoalUnavailable(projectRoot, sessionID, route, "opencode-2-without-goal-rpc");
+                await notice(sessionID, nativeGoalLine(action, { route }), key("unavailable"));
+                return;
+            }
+            case "report-user-goal": {
+                if (!said.has(key("user-goal")) && record !== undefined) {
+                    await recordNativeGoal(projectRoot, sessionID, route, { type: "native-goal.left-alone", goalID: record.id, status: record.status });
+                }
+                await notice(sessionID, nativeGoalLine(action, { route, ...(record === undefined ? {} : { goal: record }) }), key("user-goal"));
+                return;
+            }
+            case "report-conflict": {
+                if (!said.has(key("conflict"))) {
+                    await recordNativeGoal(projectRoot, sessionID, route, { type: "native-goal.conflict", goalID: record?.id ?? "", reason: action.reason });
+                }
+                await notice(sessionID, nativeGoalLine(action, { route, ...(record === undefined ? {} : { goal: record }) }), key("conflict"));
+                return;
+            }
+            case "create": {
+                const objective = nativeGoalObjective(work, sessionID);
+                try {
+                    await host.session.command({ sessionID, name: "goal", text: objective, delivery: "queue" });
+                }
+                catch (error) {
+                    await fail(sessionID, route, "create", error);
+                    return;
+                }
+                const after = await read(sessionID);
+                const created = after.supported && after.goal !== null && after.goal !== "unreadable" && after.goal.objective === objective ? after.goal : undefined;
+                if (created === undefined) {
+                    await fail(sessionID, route, "create", "the goal was not readable after /goal; ownership not claimed");
+                    return;
+                }
+                await recordNativeGoal(projectRoot, sessionID, route, { type: "native-goal.created", goalID: created.id });
+                await notice(sessionID, nativeGoalLine(action, { route, goal: created }), key("created"));
+                return;
+            }
+            case "resume":
+            case "clear": {
+                if (record === undefined)
+                    return;
+                const control = action.kind;
+                try {
+                    await host.session.command({ sessionID, name: "goal", text: control, delivery: "queue" });
+                }
+                catch (error) {
+                    await fail(sessionID, route, control, error);
+                    return;
+                }
+                const event = control === "resume" ? { type: "native-goal.resumed", goalID: record.id } : { type: "native-goal.cleared", goalID: record.id };
+                await recordNativeGoal(projectRoot, sessionID, route, event);
+                await notice(sessionID, nativeGoalLine(action, { route, goal: record }), key(control));
+                return;
+            }
+        }
+    }
+    /** One decision for one session: `route` set on an activation, absent on an idle check. */
+    async function step(sessionID, route, work) {
+        const owned = await nativeGoalOwnership(projectRoot, sessionID);
+        if (route === undefined && owned.goalID === undefined)
+            return;
+        const state = await read(sessionID);
+        const goal = state.supported ? state.goal : null;
+        const action = decideNativeGoal({
+            route,
+            supported: state.supported,
+            goal,
+            ownedGoalID: owned.goalID,
+            ledgerDone: owned.goalID === undefined ? false : await ledgerGoalDone(projectRoot, sessionID, owned.createdAt),
+            resumes: owned.resumes
+        });
+        await perform(sessionID, route, action, goal, work);
+    }
+    /** One step at a time per session, so a repeated activation sees the goal the first one made. */
+    const chains = new Map();
+    function track(sessionID, run) {
+        const previous = chains.get(sessionID) ?? Promise.resolve();
+        const safe = previous.then(run).catch(() => undefined).finally(() => {
+            running.delete(safe);
+            if (chains.get(sessionID) === safe)
+                chains.delete(sessionID);
+        });
+        chains.set(sessionID, safe);
+        running.add(safe);
+        return safe;
+    }
+    return {
+        /** Starts the goal step for a qualifying activation without holding up the user's prompt. */
+        activate(sessionID, route, work) {
+            return track(sessionID, () => step(sessionID, route, work));
+        },
+        /** The session finished its model work: clear a finished owned goal or report a conflict. */
+        idle(sessionID) {
+            return track(sessionID, () => step(sessionID, undefined, ""));
+        },
+        /** Resolves when every started goal step has finished. */
+        async settled() {
+            while (running.size > 0)
+                await Promise.all([...running]);
+        }
+    };
+}

package/dist/v2/native-goal.d.ts

@@ -0,0 +1,49 @@
+export type NativeGoalRoute = "lit-loop" | "start-work" | "litwork";
+export type NativeGoalRecord = {
+    readonly id: string;
+    readonly objective: string;
+    readonly status: "active" | "paused" | "complete";
+    readonly reason?: string;
+};
+export type NativeGoalInput = {
+    /** The route that is activating now; absent on an idle check. */
+    readonly route: string | undefined;
+    /** Whether this host answers the `opencode.goal` RPC. */
+    readonly supported: boolean;
+    /** The host's goal for the session: null when none, "unreadable" when the read failed. */
+    readonly goal: NativeGoalRecord | null | "unreadable";
+    /** The goal id LitOpenCode created for this session, from its ledger. */
+    readonly ownedGoalID: string | undefined;
+    /** Whether LitOpenCode's evidence ledger marks the session's goal complete. */
+    readonly ledgerDone: boolean;
+    /** How many times LitOpenCode already resumed the owned goal. */
+    readonly resumes: number;
+};
+export type NativeGoalAction = {
+    readonly kind: "none";
+} | {
+    readonly kind: "create";
+} | {
+    readonly kind: "keep";
+} | {
+    readonly kind: "resume";
+} | {
+    readonly kind: "clear";
+} | {
+    readonly kind: "report-user-goal";
+} | {
+    readonly kind: "report-conflict";
+    readonly reason: string;
+} | {
+    readonly kind: "unavailable";
+};
+/** The qualifying route for a chat mode or command id, or undefined for every other route. */
+export declare function nativeGoalRoute(mode: string, text: string): NativeGoalRoute | undefined;
+export declare function decideNativeGoal(input: NativeGoalInput): NativeGoalAction;
+/** The text sent to `/goal`: the work, then the conditions OpenCode's reviewer judges it against. */
+export declare function nativeGoalObjective(work: string, sessionID?: string): string;
+/** The single line announced for an action; an empty string when nothing changed. */
+export declare function nativeGoalLine(action: NativeGoalAction, detail: {
+    readonly route?: string;
+    readonly goal?: Pick<NativeGoalRecord, "id" | "status" | "objective">;
+}): string;

package/dist/v2/native-goal.js

@@ -0,0 +1,71 @@
+// Policy for OpenCode 2's native `/goal`. It is pure: the route, the goal record the host reports and the
+// state of LitOpenCode's own ledger go in; one action comes out. The host has no setter for a goal, only
+// the `/goal` command, and that command replaces any goal that exists, so every create is decided here
+// first. LitOpenCode manages only a goal it created (the ledger remembers the id); a goal the user made
+// is reported and never touched. Done needs two things: OpenCode's verdict and the ledger.
+import { containsSecret } from "../secret-shapes.js";
+const goalRoutes = new Set(["lit-loop", "start-work", "litwork"]);
+/** The host pauses a goal on a restart; it is the only pause that is safe to resume without asking. */
+const restartPause = "The server restarted while the goal was active";
+const maxResumes = 2;
+const maxObjective = 4000;
+const completionConditions = "Done only when all of these hold: the change works and the project's tests pass; a real-surface check of the path a user touches has run; temporary files are cleaned up with a cleanup receipt; and LitOpenCode's evidence ledger (.litopencode/litgoal) marks the goal complete.";
+/** The qualifying route for a chat mode or command id, or undefined for every other route. */
+export function nativeGoalRoute(mode, text) {
+    if (mode === "lit-loop" || mode === "start-work")
+        return mode;
+    if (mode === "litwork" || mode === "lit-work")
+        return "litwork";
+    if (mode !== "lit-task")
+        return undefined;
+    const first = text.trim().replace(/^\//u, "").split(/\s+/u)[0]?.toLowerCase();
+    return first === "litwork" || first === "lit-work" ? "litwork" : undefined;
+}
+export function decideNativeGoal(input) {
+    const routed = input.route !== undefined;
+    if (routed && !goalRoutes.has(input.route))
+        return { kind: "none" };
+    if (!input.supported)
+        return routed ? { kind: "unavailable" } : { kind: "none" };
+    const goal = input.goal;
+    if (goal === "unreadable")
+        return routed ? { kind: "report-conflict", reason: "the goal state could not be read, so none was set" } : { kind: "none" };
+    if (goal === null)
+        return routed ? { kind: "create" } : { kind: "none" };
+    if (input.ownedGoalID === undefined || goal.id !== input.ownedGoalID)
+        return routed ? { kind: "report-user-goal" } : { kind: "none" };
+    if (goal.status === "complete") {
+        return input.ledgerDone ? { kind: "clear" } : { kind: "report-conflict", reason: "OpenCode says the goal is met but the ledger is still open" };
+    }
+    if (goal.status === "paused") {
+        if (goal.reason === restartPause && input.resumes < maxResumes)
+            return routed ? { kind: "resume" } : { kind: "none" };
+        return routed ? { kind: "report-conflict", reason: `the goal is paused${goal.reason === undefined ? "" : ` (${oneLine(goal.reason, 60)})`} and needs a person to resume it` } : { kind: "none" };
+    }
+    return { kind: "keep" };
+}
+function oneLine(value, limit) {
+    const flat = value.replace(/\s+/gu, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+}
+/** The text sent to `/goal`: the work, then the conditions OpenCode's reviewer judges it against. */
+export function nativeGoalObjective(work, sessionID) {
+    const flat = work.replace(/\s+/gu, " ").trim();
+    const subject = flat === "" || containsSecret(flat) ? "the work requested in this session" : flat;
+    const conditions = sessionID === undefined || !/^[A-Za-z0-9_-]{1,80}$/u.test(sessionID) ? completionConditions : `${completionConditions} Open that ledger goal with --session-id ${sessionID}.`;
+    const room = maxObjective - conditions.length - 2;
+    return `${oneLine(subject, room)}\n\n${conditions}`;
+}
+/** The single line announced for an action; an empty string when nothing changed. */
+export function nativeGoalLine(action, detail) {
+    const id = detail.goal === undefined ? "" : ` ${detail.goal.id.slice(0, 8)}`;
+    switch (action.kind) {
+        case "create": return `LitOpenCode goal: created for ${detail.route ?? "this work"}; OpenCode judges it, the ledger must agree`;
+        case "resume": return `LitOpenCode goal: resumed${id} after a server restart`;
+        case "clear": return `LitOpenCode goal: cleared${id}; OpenCode's verdict and the ledger both say done`;
+        case "report-user-goal": return `LitOpenCode goal: left yours alone${detail.goal === undefined ? "" : ` (${detail.goal.status}: ${oneLine(detail.goal.objective, 60)})`}`;
+        case "report-conflict": return `LitOpenCode goal: conflict, ${oneLine(action.reason, 120)}; not reporting done`;
+        case "unavailable": return "LitOpenCode goal: native-goal-unavailable (this OpenCode has no /goal); the ledger carries the work";
+        default: return "";
+    }
+}

package/dist/v2/server.js

@@ -11,6 +11,7 @@ import { applyLitAgents, createSessionModelRoute, enforcePlanningOnly, planLitAg
 import { createSessionLookupV2, projectRootFromLocation } from "./context.js";
 import { createV2Commands } from "./commands.js";
 import { createV2Events } from "./events.js";
+import { createNativeGoal } from "./native-goal-runtime.js";
 import { createV2ToolHooks } from "./hooks.js";
 import { createV2SessionHooks } from "./session-hooks.js";
 import { addLitTools, litToolsForProject } from "./tools.js";
@@ -46,6 +47,7 @@ export async function setupLitOpenCodeServer(context) {
         model: context.model,
         onSessionDeleted: (sessionID) => sessionHooks.clear(sessionID)
     });
+    const nativeGoal = createNativeGoal({ projectRoot: root, host: { ...(context.rpc === undefined ? {} : { rpc: context.rpc }), session: context.session } });
     const sessionHooks = createV2SessionHooks({
         projectRoot: root,
         config: loaded.config,
@@ -54,14 +56,22 @@ export async function setupLitOpenCodeServer(context) {
         requestOptions: agentPlan.requestOptions,
         autoHandoffRoute: events.route,
         extraSystem: events.systemText,
-        acceptCommandMark: commands.acceptMark
+        acceptCommandMark: commands.acceptMark,
+        nativeGoal
     });
     await context.session.hook("prompt", sessionHooks.prompt);
     await context.session.hook("context", sessionHooks.context);
     await context.session.hook("compaction", sessionHooks.compaction);
+    try {
+        await context.session.hook("experimental.idle", ({ sessionID }) => nativeGoal.idle(sessionID));
+    }
+    catch { // no-excuse-ok: catch -- an OpenCode 2 build without the idle hook has no native /goal either; the plugin still starts.
+        // Activation-time goal handling still runs; only the finished-goal check is missing.
+    }
     const stopEvents = events.start(context.event);
     return async () => {
         await stopEvents();
+        await nativeGoal.settled();
         deliverableHedgeGuard.dispose();
         await logger.dispose();
     };

package/dist/v2/session-hooks.d.ts

@@ -2,6 +2,7 @@ import { type ChatActivationMode } from "../activation-routing.ts";
 import { type AutoHandoffRouteMode } from "../auto-handoff.ts";
 import type { LitOpenCodeConfig } from "../config.ts";
 import type { AgentRequestOptions } from "./agents.ts";
+import { type NativeGoal } from "./native-goal-runtime.ts";
 export type SystemPartLike = {
     readonly type: "text";
     readonly text: string;
@@ -45,7 +46,10 @@ export type V2SessionHookOptions = {
     readonly acceptCommandMark?: (sessionID: string, marker: unknown) => {
         readonly command: string;
         readonly banner: string;
+        readonly work?: string;
     } | undefined;
+    /** Sets and manages OpenCode 2's native goal for lit-loop, start-work and litwork. */
+    readonly nativeGoal?: NativeGoal;
 };
 /**
  * `opencode2 run "lit fix it"` sends the message wrapped in double quotes (each multi-word argument is

package/dist/v2/session-hooks.js

@@ -17,6 +17,8 @@ import { startTypedWork, typedStartArgument } from "../start-work-typed.js";
 import { createLitGoalOperations } from "../ledger.js";
 import { applyCompactionRuleReset, applyStaticRuleInjection } from "../rules/hooks.js";
 import { isReadOnlyWorkflowFamilyPlan } from "../workflow-families.js";
+import { aliasGoalRoute } from "./native-goal-runtime.js";
+import { nativeGoalRoute } from "./native-goal.js";
 const bundledRulesDir = fileURLToPath(new URL("../../rules/bundled-rules", import.meta.url));
 /**
  * `opencode2 run "lit fix it"` sends the message wrapped in double quotes (each multi-word argument is
@@ -63,6 +65,12 @@ export function createV2SessionHooks(options) {
         }
         return state;
     }
+    /** Starts the native-goal step for a qualifying route; it never holds up or fails the prompt. */
+    function startNativeGoal(sessionID, route, work) {
+        if (route === undefined || options.nativeGoal === undefined)
+            return;
+        void options.nativeGoal.activate(sessionID, route, work);
+    }
     async function lookup(sessionID) {
         try {
             const session = await options.getSession(sessionID);
@@ -88,6 +96,7 @@ export function createV2SessionHooks(options) {
         }
         event.metadata = { ...rest, litopencode: { command: accepted.command, banner: accepted.banner, source: "command" } };
         options.onActivation?.(event.sessionID, accepted.command);
+        startNativeGoal(event.sessionID, nativeGoalRoute(accepted.command, ""), accepted.work ?? "");
         return true;
     }
     async function prompt(event) {
@@ -143,9 +152,13 @@ export function createV2SessionHooks(options) {
             options.onActivation?.(event.sessionID, "lit-adhd");
             return;
         }
+        const alias = aliasGoalRoute(input);
+        if (alias !== undefined)
+            startNativeGoal(event.sessionID, alias.route, alias.work);
         const mode = detectChatActivationMode(input, session.agent);
         if (mode === undefined)
             return;
+        startNativeGoal(event.sessionID, nativeGoalRoute(mode, input), input);
         const trigger = mode === "lit-handoff" ? "handoff" : mode === "lit-scientific-visualization" ? mode : "lit";
         let activation = promptForChatActivationMode(mode, input);
         if (mode === "lit-adhd")

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.34"><title>release: 1.0.34</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.34</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.36"><title>release: 1.0.36</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.36</text></g></svg>

package/docs/migration.md

@@ -29,7 +29,7 @@ This guide describes the supported migration shape for moving an OpenCode workfl
 - Planning routes now produce proportionate objective-achievable checklists rather than relying on a later review pass to discover missing execution detail. Each retained item carries action/output/verification, while risky or multi-stage work receives SDD-like gates only when justified. `/review-work` accepts both draft plans (read-only `PASS`/`ITERATE`/`NEEDS-CONTEXT`) and completed work (the existing five-lane review); it never implements a draft plan.
 - Keep `/start-work` as the native executable handoff to `lit-implement`. Chat-only start-work activation must begin with `start-work` or `lit start work`; diagnostic, copied, quoted, and blockquote mentions must not select start-work or append a false start-work event. An independent final `lit` remains an ordinary `lit-loop` activation.
 - Schema-3 bounded-authority state is package-owned under `.litopencode/litgoal/lit-loop`. Existing activity ledgers remain readable; strict `/start-work init|resume|cancel|complete|status` directives create and advance the separate work snapshot and bounded journal. Resume is trusted-user-only and the generic `start-work` tool does not gain a resume action.
-- Do not claim native goal binding unless the current OpenCode CLI or plugin API exposes a goal primitive; use LitOpenCode-owned `.litopencode/litgoal` state for durable goal behavior.
+- Native goal binding exists only on OpenCode 2.2 and later (the `opencode.goal` RPC and the `/goal` command) and only for lit-loop, start-work and litwork; on OpenCode 1 and older OpenCode 2 hosts do not claim it, and keep LitOpenCode-owned `.litopencode/litgoal` state as the evidence record everywhere.
 
 ## Durable State
 

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
@@ -229,8 +255,11 @@ folder would cover it. Paths in code fences and commands quoted in an inline cod
 When typed start-work begins, each valid `Scope roots:` line becomes a grant of the run, so it does
 not pause for a folder the approved plan named; the folder must exist then.
 
-Native goal verdict: the OpenCode host surface does not currently expose a native goal primitive;
-LitOpenCode uses `.litopencode/litgoal` instead. Static skills are installed under
+Native goal verdict: OpenCode 2.2 and later has a native `/goal`, and LitOpenCode sets, resumes and
+clears one only for lit-loop, start-work and litwork, only for goals it created; a goal you made is
+reported and left alone. OpenCode 1 and older OpenCode 2 hosts record `native-goal-unavailable`.
+The ledger under `.litopencode/litgoal` is the evidence record on every host, and done needs both
+OpenCode's verdict and the ledger. Static skills are installed under
 `skills/*/SKILL.md` and remain documentation unless a documented OpenCode route selects them.
 
 ## Skill learning state
@@ -370,7 +399,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.34",
+  "version": "1.0.36",
   "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",
@@ -74,7 +74,7 @@
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.6",
-    "@opencode/plugin": "2.0.32",
+    "@opencode/plugin": "2.2.5",
     "@types/node": "^24.12.2",
     "picomatch": "^4.0.5",
     "typescript": "^5.9.3"

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.