dsh-task-ledger 0.0.125 → 0.0.127

package/dist/host/errors.d.ts

@@ -8,7 +8,13 @@
  *   防止「台账程序根本没装」被集体降级成一片绿色空板——那等于界面撒谎。
  */
 /** 机器可读错误码（只增不改；`LEDGER_` 前缀避开宿主错误码空间）。 */
-export type LedgerErrorCode = "LEDGER_SCRIPT_UNAVAILABLE" | "LEDGER_SCRIPT_TIMEOUT" | "LEDGER_SCRIPT_FAILED" | "LEDGER_SCRIPT_BAD_JSON" | "LEDGER_DATA_INVALID";
+export type LedgerErrorCode = "LEDGER_SCRIPT_UNAVAILABLE" | "LEDGER_SCRIPT_TIMEOUT" | "LEDGER_SCRIPT_FAILED" | "LEDGER_SCRIPT_BAD_JSON" | "LEDGER_DATA_INVALID" | "LEDGER_IDENTITY_MISSING";
+/** 这台机器还没有身份。message 仍是脚本原文（可直接上界面），码用来分流。 */
+export declare class IdentityMissingError extends Error {
+    readonly code: LedgerErrorCode;
+    readonly workspaceId: string | null;
+    constructor(message: string, workspaceId?: string | null);
+}
 /** 台账数据形状不符（容器级校验失败）。message 带工作区名 + 人话，可直接上界面。 */
 export declare class LedgerDataError extends Error {
     readonly code: LedgerErrorCode;
@@ -20,7 +26,7 @@ export interface DegradedInfo {
     readonly workspaceId: string;
     readonly workspaceTitle: string;
     /** 哪个读挂了（skill 子命令；趋势走 `stats --trend`，单独一档便于区分）。 */
-    readonly op: "list" | "owners" | "trend";
+    readonly op: "list" | "owners" | "trend" | "history";
     readonly code: LedgerErrorCode;
     /** 人话，可直接上界面（真源：脚本 stderr / records 校验文案）。 */
     readonly message: string;
@@ -36,7 +42,7 @@ export declare function messageOf(error: unknown): string;
 export declare function settleWorkspaces<W extends {
     id: string;
     title: string;
-}, T, R>(workspaces: readonly W[], op: "list" | "owners", read: (workspace: W) => Promise<T>, merge: (rows: readonly T[]) => R): Promise<{
+}, T, R>(workspaces: readonly W[], op: "list" | "owners" | "history", read: (workspace: W) => Promise<T>, merge: (rows: readonly T[]) => R): Promise<{
     data: R;
     degraded: readonly DegradedInfo[];
 }>;

package/dist/host/errors.js

@@ -7,6 +7,16 @@
  * - **全局失败**（所有工作区都读不到 / 编程错误）：照旧抛，路由转 500 + 人话。
  *   防止「台账程序根本没装」被集体降级成一片绿色空板——那等于界面撒谎。
  */
+/** 这台机器还没有身份。message 仍是脚本原文（可直接上界面），码用来分流。 */
+export class IdentityMissingError extends Error {
+    code = "LEDGER_IDENTITY_MISSING";
+    workspaceId;
+    constructor(message, workspaceId = null) {
+        super(message);
+        this.name = "IdentityMissingError";
+        this.workspaceId = workspaceId;
+    }
+}
 /** 台账数据形状不符（容器级校验失败）。message 带工作区名 + 人话，可直接上界面。 */
 export class LedgerDataError extends Error {
     code = "LEDGER_DATA_INVALID";

package/dist/host/repositories/cache.d.ts

@@ -11,8 +11,8 @@
 /** 缓存有效期（2026-10-18 拍板 1.5s：够挡同一屏的重复读，短到不会让人看到旧数据）。 */
 export declare const CACHE_TTL_MS = 1500;
 /** 缓存的操作种类（= skill 脚本子命令；worklog 不进缓存故不在此列）。
- *  `history` 已从插件侧消失（2026-10-29：本周 / 上周完成改取 `stats --trend` 的桶），不再单列。 */
-export type CacheOp = "list" | "stats" | "owners";
+ *  `history` 供历史页顶部日趋势使用（2026-10-29 重新接入）。 */
+export type CacheOp = "history" | "list" | "stats" | "owners";
 /** 缓存键：`op:workspace:filter` 三条信息都要，否则不同筛选 / 不同工作区会串味。 */
 export declare function cacheKey(workspaceId: string, op: CacheOp, detail: string): string;
 /**

package/dist/host/repositories/dirs.repository.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 机器级台账目录清单（`~/.taskledger/ledgers.json`，真源在 skill 侧）。
+ *
+ * **写只走 skill**（`dirs --add`），插件只读 —— 将来的其它看板（网页 / APP）也照此办理，
+ * 免得两套写法把同一个文件写坏（2026-11-01 用户拍板）。
+ */
+export interface LedgerDir {
+    readonly path: string;
+    readonly name: string;
+    readonly hidden: boolean;
+}
+/**
+ * 读清单。skill 侧会顺手清掉失效条目（目录没了 / 已经不是台账）再返回。
+ * 损坏的清单按空处理，不让「看台账」这件事失败。
+ */
+export declare function readDirs(): Promise<LedgerDir[]>;
+/** 看板上显示 / 不显示这一个台账（只动清单，目录与台账文件一个都不碰）。 */
+export declare function setDirHidden(path: string, hidden: boolean): Promise<LedgerDir[]>;
+/** 改台账名；空名 = 回落目录名（skill 口径）。 */
+export declare function renameDir(path: string, name: string): Promise<LedgerDir[]>;
+/** 从清单移除（不是删目录：台账数据与文件全部原样保留）。 */
+export declare function removeDir(path: string): Promise<LedgerDir[]>;
+/**
+ * 登记一个目录（幂等）。不是台账根时 skill 返回 `added:false` + 原因，不算错误。
+ * 返回登记后的整份清单，调用方不必再读一次。
+ */
+export declare function addDir(path: string, name: string): Promise<{
+    readonly dirs: LedgerDir[];
+    readonly added: boolean;
+    readonly reason: string;
+}>;
+/**
+ * 一级子目录里的台账根。用户 2026-11-03：只知道「这个项目有台账」的人会选它的**直属父目录**，
+ * 这种选择也算有效 —— 父目录本身不进清单（清单只存台账根），登记它下面这些。
+ * 目录读不了 / 没有台账 ⇒ 空数组，由调用方出提示。
+ */
+export declare function ledgerChildrenOf(path: string): Promise<string[]>;

package/dist/host/repositories/dirs.repository.js

@@ -0,0 +1,97 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { failureOf, runLedgerScript } from "./runner.js";
+function parseDirs(data) {
+    const rows = Array.isArray(data.dirs) ? data.dirs : [];
+    const out = [];
+    for (const row of rows) {
+        if (typeof row?.path !== "string" || row.path === "")
+            continue;
+        out.push({
+            path: row.path,
+            name: typeof row.name === "string" ? row.name : "",
+            hidden: row.hidden === true,
+        });
+    }
+    return out;
+}
+/**
+ * 读清单。skill 侧会顺手清掉失效条目（目录没了 / 已经不是台账）再返回。
+ * 损坏的清单按空处理，不让「看台账」这件事失败。
+ */
+export async function readDirs() {
+    // --all：必须拿到隐藏项，否则「这些路径已登记过」判不出来，每轮都会把它们当新目录反复补登记
+    const result = await runLedgerScript("dirs", ["--all", "--json"]);
+    if (!result.ok)
+        throw failureOf(result, "读台账目录清单失败：");
+    return parseDirs(result.data);
+}
+/**
+ * 写动作的公共出口：skill 的写命令**恒回全量清单**（含隐藏项，`actions/dirs.go:201`），
+ * 调用方拿它就地换掉表格，不必再读一次。
+ */
+async function writeDirs(args) {
+    const result = await runLedgerScript("dirs", [...args, "--json"]);
+    if (!result.ok)
+        throw failureOf(result, "改台账目录清单失败：");
+    return parseDirs(result.data);
+}
+/** 看板上显示 / 不显示这一个台账（只动清单，目录与台账文件一个都不碰）。 */
+export function setDirHidden(path, hidden) {
+    return writeDirs(["--dir", path, hidden ? "--hide" : "--unhide"]);
+}
+/** 改台账名；空名 = 回落目录名（skill 口径）。 */
+export function renameDir(path, name) {
+    return writeDirs(["--dir", path, "--rename", name]);
+}
+/** 从清单移除（不是删目录：台账数据与文件全部原样保留）。 */
+export function removeDir(path) {
+    return writeDirs(["--dir", path, "--remove"]);
+}
+/**
+ * 登记一个目录（幂等）。不是台账根时 skill 返回 `added:false` + 原因，不算错误。
+ * 返回登记后的整份清单，调用方不必再读一次。
+ */
+export async function addDir(path, name) {
+    const args = ["--dir", path, "--add", "--json"];
+    if (name !== "")
+        args.push("--name", name);
+    const result = await runLedgerScript("dirs", args);
+    if (!result.ok)
+        throw failureOf(result, "登记台账目录失败：");
+    return {
+        dirs: parseDirs(result.data),
+        added: result.data.added === true,
+        reason: typeof result.data.reason === "string" ? result.data.reason : "",
+    };
+}
+/** 目录下**直接**含 `ledger/` ⇒ 台账根（与 skill `root` 同一判据：`core/roots.go:35`）。 */
+async function hasLedger(dir) {
+    try {
+        return (await stat(join(dir, "ledger"))).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 一级子目录里的台账根。用户 2026-11-03：只知道「这个项目有台账」的人会选它的**直属父目录**，
+ * 这种选择也算有效 —— 父目录本身不进清单（清单只存台账根），登记它下面这些。
+ * 目录读不了 / 没有台账 ⇒ 空数组，由调用方出提示。
+ */
+export async function ledgerChildrenOf(path) {
+    let names;
+    try {
+        names = await readdir(path);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names.sort()) {
+        const child = join(path, name);
+        if (await hasLedger(child))
+            found.push(child);
+    }
+    return found;
+}

package/dist/host/repositories/history.repository.d.ts

@@ -0,0 +1,20 @@
+import type { HistoryRecord, LedgerWorkspace } from "../types.js";
+/**
+ * 历史明细（skill `history --json`）：按**结案时间**过滤，新→旧。
+ *
+ * 分页口径：skill 没有 offset，只有时间窗 + `--limit` ⇒ 下一页用「本页最后一条的
+ * `finished`」当新的 `--until`（含边界，跨页会重叠几条，由上层按 key 去重）。
+ */
+export interface HistoryQueryOptions {
+    /** `YYYY-MM-DD HH:MM:SS`（与存盘同形的串，脚本直接字符串比较）。 */
+    readonly since: string;
+    readonly until: string;
+    /** 不给 = 整月全量（2026-11-01 起历史列表按整月取，不再封顶）。 */
+    readonly limit?: number;
+    /** 执行人 uuid；不给 = 不限。 */
+    readonly owner?: string;
+}
+export declare function readHistory(workspace: LedgerWorkspace, options: HistoryQueryOptions): Promise<{
+    records: HistoryRecord[];
+    capped: boolean;
+}>;

package/dist/host/repositories/history.repository.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { cached, cacheKey } from "./cache.js";
+import { failureOf, runLedgerScript } from "./runner.js";
+/** 脚本一行 → 带工作区身份的记录（缺字段一律空串，不编造）。 */
+function toRecord(raw, workspace) {
+    const src = typeof raw.src === "string" ? raw.src : "";
+    const line = typeof raw.line === "number" ? raw.line : 0;
+    const text = (value) => typeof value === "string" ? value : "";
+    return {
+        // ⚠️ 必须带工作区：各仓的 src 都是 `ledger/history/YYYYMM.md`、line 各自编号，
+        // 只用 src:line 会让不同工作区的记录撞成同一个 key，合并去重时被当成重复吞掉。
+        key: `${workspace.id}:${src}:${String(line)}`,
+        workspaceId: workspace.id,
+        workspaceTitle: workspace.title,
+        title: text(raw.title),
+        summary: text(raw.summary),
+        category: text(raw.category),
+        tags: Array.isArray(raw.tags)
+            ? raw.tags.filter((tag) => typeof tag === "string")
+            : [],
+        result: text(raw.result),
+        owner: text(raw.owner),
+        ownerName: text(raw.owner_name),
+        creator: text(raw.creator),
+        creatorName: text(raw.creator_name),
+        created: text(raw.created),
+        finished: text(raw.finished),
+        // worklog 是相对**历史文件所在目录**的串（`../worklog/202610/x.md`）⇒ 这一步算成绝对路径，
+        // 前端拿去直接开预览（页面不许自己拼台账布局）。空 = 这行没有过程文档。
+        filePath: text(raw.worklog) === ""
+            ? ""
+            : path.join(workspace.path, "ledger", "history", text(raw.worklog)),
+    };
+}
+export async function readHistory(workspace, options) {
+    const args = [
+        "--repo",
+        workspace.path,
+        "--json",
+        "--since",
+        options.since,
+        "--until",
+        options.until,
+    ];
+    if (options.limit !== undefined)
+        args.push("--limit", String(options.limit));
+    if (options.owner !== undefined)
+        args.push("--owner", options.owner);
+    return await cached(cacheKey(workspace.id, "history", args.slice(2).join("\u0001")), async () => {
+        const result = await runLedgerScript("history", args);
+        if (!result.ok)
+            throw failureOf(result, `${workspace.title}: `, workspace.id);
+        const rows = result.data.records;
+        if (!Array.isArray(rows))
+            throw new Error(`${workspace.title}: history 输出缺 records 数组`);
+        return {
+            records: rows
+                .filter((row) => row !== null && typeof row === "object")
+                .map((row) => toRecord(row, workspace)),
+            capped: result.data.capped === true,
+        };
+    });
+}

package/dist/host/repositories/identity.repository.d.ts

@@ -1,10 +1,60 @@
 import type { LedgerWorkspace } from "../types.js";
 /**
- * 本机身份 uuid —— 走 skill `whoami --json`（**不再自己读 identity.json**：
+ * 本机身份 —— 走 skill `whoami --json` / `switch --json`（**不自己读 identity.json**：
  * `$TASK_LEDGER_HOME` / 默认目录 / 文件格式都是 skill 的知识，插件不复制第二份）。
  *
- * **只取 `uuid`**：`name` 是冗余显示字段，不参与任何判定（按名字比 owner 永远比不到）。
- * 未初始化时 skill 回 `{"uuid":null}`（退 0），这里同样回 null ⇒ 「我的」按 0 计（不谎报）。
+ * 未初始化时 skill 回 `{"uuid":null,"name":null}`（退 0）⇒ 这里同样回 null ⇒ 「我的」按 0 计（不谎报）。
  * 程序起不来看不出身份，也只回 null。
  */
+/** 本机身份；`uuid === null` = 这台机器还没有身份。 */
+export interface IdentityView {
+    readonly uuid: string | null;
+    readonly name: string | null;
+}
+/** 换身份：建全新身份 / 认领某个工作区名册里已有的人 / 改自己的昵称。 */
+export type SwitchInput = {
+    readonly action: "new";
+    readonly name: string;
+} | {
+    readonly action: "claim";
+    readonly uuid: string;
+    readonly repo: string;
+} | {
+    readonly action: "rename";
+    readonly name: string;
+};
+/** 改昵称时某一本台账的结果（skill `switch --rename --json` 的 `dirs[]`）。 */
+export interface RenameDirResult {
+    readonly dir: string;
+    /** changed = 改了且提交推送成功；commit-only = 改了但只提交在本地；skipped = 没改；failed = 出错。 */
+    readonly status: "changed" | "commit-only" | "skipped" | "failed";
+    readonly reason: string;
+}
+/** 改昵称的回执：新昵称 + 每本台账各自的结果（跨仓库做不到全成或全败）。 */
+export interface RenameView {
+    readonly uuid: string;
+    readonly name: string;
+    readonly previous: string;
+    readonly dirs: readonly RenameDirResult[];
+}
+export declare function readIdentity(): Promise<IdentityView>;
+/** 只要 uuid（看板行级的「是不是我的」以 skill 的 `mine` 为准，这里只备查）。 */
 export declare function getCurrentIdentity(_workspace?: LedgerWorkspace): Promise<string | null>;
+/**
+ * 换身份。调的是隐藏命令 `switch`（不进 SKILL.md）：它允许覆盖已有身份、不受真终端限制，
+ * 正是 `init` 做不到的两件事。失败把人话抛给路由（→ 500 → 界面原地显示）。
+ */
+export declare function switchIdentity(input: SwitchInput): Promise<IdentityView | RenameView>;
+/** 从一本台账的名册里摘掉一个人（skill `forget --json`）。 */
+export interface ForgetOutcome {
+    /** false = 分片里还有任务，这本台账没删。 */
+    readonly removed: boolean;
+    readonly name: string;
+    readonly tasks: number;
+}
+export declare function forgetOwner(repo: string, uuid: string): Promise<ForgetOutcome>;
+/**
+ * 清掉本机身份（skill `logout`）：台账一个字节都不动。
+ * 只删 ~/.taskledger/identity.json —— 路径归 skill 管，插件不复制这份知识。
+ */
+export declare function logout(repo: string): Promise<void>;

package/dist/host/repositories/identity.repository.js

@@ -1,16 +1,111 @@
 import { runLedgerScript } from "./runner.js";
 /**
- * 本机身份 uuid —— 走 skill `whoami --json`（**不再自己读 identity.json**：
- * `$TASK_LEDGER_HOME` / 默认目录 / 文件格式都是 skill 的知识，插件不复制第二份）。
- *
- * **只取 `uuid`**：`name` 是冗余显示字段，不参与任何判定（按名字比 owner 永远比不到）。
- * 未初始化时 skill 回 `{"uuid":null}`（退 0），这里同样回 null ⇒ 「我的」按 0 计（不谎报）。
- * 程序起不来看不出身份，也只回 null。
+ * 改昵称的超时：要逐本台账走「取最新 → 改 → 提交 → 推送」，
+ * 一本就可能几秒，十个目录轻松过一分钟 —— 绝不能吃默认的 10s。
  */
-export async function getCurrentIdentity(_workspace) {
+const RENAME_TIMEOUT_MS = 180_000;
+/** 删人同样逐本台账走 git（取最新 → 改 → 提交 → 推送），10s 默认值不够。 */
+const FORGET_TIMEOUT_MS = 120_000;
+const UNKNOWN_IDENTITY = { uuid: null, name: null };
+function viewOf(data) {
+    const uuid = typeof data.uuid === "string" ? data.uuid.trim() : "";
+    const name = typeof data.name === "string" ? data.name.trim() : "";
+    return {
+        uuid: uuid === "" ? null : uuid.toLowerCase(),
+        name: name === "" ? null : name,
+    };
+}
+export async function readIdentity() {
     const result = await runLedgerScript("whoami", ["--json"]);
     if (!result.ok)
-        return null;
-    const uuid = typeof result.data.uuid === "string" ? result.data.uuid.trim() : "";
-    return uuid === "" ? null : uuid.toLowerCase();
+        return UNKNOWN_IDENTITY;
+    return viewOf(result.data);
+}
+/** 只要 uuid（看板行级的「是不是我的」以 skill 的 `mine` 为准，这里只备查）。 */
+export async function getCurrentIdentity(_workspace) {
+    return (await readIdentity()).uuid;
+}
+/**
+ * 换身份。调的是隐藏命令 `switch`（不进 SKILL.md）：它允许覆盖已有身份、不受真终端限制，
+ * 正是 `init` 做不到的两件事。失败把人话抛给路由（→ 500 → 界面原地显示）。
+ */
+export async function switchIdentity(input) {
+    const args = ["--json"];
+    if (input.action === "rename") {
+        args.push("--rename", input.name);
+    }
+    else if (input.action === "new") {
+        args.push("--new", "--name", input.name);
+    }
+    else {
+        args.push("--claim", input.uuid, "--repo", input.repo);
+    }
+    const result = await runLedgerScript("switch", args, {
+        timeoutMs: input.action === "rename" ? RENAME_TIMEOUT_MS : undefined,
+    });
+    if (!result.ok)
+        throw new Error(result.error);
+    if (input.action === "rename") {
+        const identity = viewOf(result.data);
+        if (identity.uuid === null || identity.name === null)
+            throw new Error("改昵称的回执里没有身份（脚本输出异常）");
+        return {
+            uuid: identity.uuid,
+            name: identity.name,
+            previous: typeof result.data.previous === "string" ? result.data.previous : "",
+            dirs: dirsOf(result.data.dirs),
+        };
+    }
+    return viewOf(result.data);
+}
+export async function forgetOwner(repo, uuid) {
+    // 删人也走一遍「写前取最新 → 改 → 提交 → 推送」，一次网络往返就可能几秒，
+    // 默认的 10s 会把它判超时（脚本被 kill 时连分片都还没删）。
+    //
+    // **--keep-identity**：界面删自己会逐本台账各跑一次，谁先跑完谁把 identity.json 删了，
+    // 后面几本就会报「这台机器还没有初始化身份」（用户 2026-11-02 实测）。清身份留到最后一步。
+    const result = await runLedgerScript("forget", ["--id", uuid, "--keep-identity", "--repo", repo, "--json"], {
+        timeoutMs: FORGET_TIMEOUT_MS,
+    });
+    if (!result.ok)
+        throw new Error(result.error);
+    return {
+        removed: result.data.removed === true,
+        name: typeof result.data.name === "string" ? result.data.name : "",
+        tasks: typeof result.data.tasks === "number" ? result.data.tasks : 0,
+    };
+}
+/**
+ * 清掉本机身份（skill `logout`）：台账一个字节都不动。
+ * 只删 ~/.taskledger/identity.json —— 路径归 skill 管，插件不复制这份知识。
+ */
+export async function logout(repo) {
+    const result = await runLedgerScript("logout", ["--json", "--repo", repo], { timeoutMs: 30_000 });
+    if (!result.ok)
+        throw new Error(result.error);
+}
+/** `dirs[]` 原样搬过来（形状不对的行直接丢掉，不编造）。 */
+function dirsOf(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const row of raw) {
+        if (row === null || typeof row !== "object")
+            continue;
+        const item = row;
+        if (typeof item.dir !== "string")
+            continue;
+        const status = item.status;
+        if (status !== "changed" &&
+            status !== "commit-only" &&
+            status !== "skipped" &&
+            status !== "failed")
+            continue;
+        out.push({
+            dir: item.dir,
+            status,
+            reason: typeof item.reason === "string" ? item.reason : "",
+        });
+    }
+    return out;
 }

package/dist/host/repositories/ledger.repository.d.ts

@@ -5,14 +5,6 @@ import type { LedgerFilter, LedgerWorkspace, TaskRow, WorkspaceOwners } from "..
  * 参数名以 `skill/shell/cli.go` 的 `list` 白名单为准，拼错一个就让 argparse 退 2、整块列表 500。
  */
 export declare function filterArgs(filter: LedgerFilter): string[];
-/**
- * 台账工作区探测：走 skill `root --json`（判据是「这个目录直接含 `ledger/`」，
- * 与脚本定位工作区根同一口径；有没有 `pool.json` 不影响）。
- *
- * 曾经的 `<path>/ledger/pool.json` 直查已废——布局知识只留 skill 一份。
- * 程序起不来时抛错（不静默把工作区藏掉）。
- */
-export declare function hasLedger(workspacePath: string): Promise<boolean>;
 /**
  * 在办任务（包 `list --json`；结果过 records 入口校验后打上 workspace）。
  * 脚本失败 / 形状不符抛错——由 service 层捕获进 degraded，路由层转 500 + 人话，

package/dist/host/repositories/ledger.repository.js

@@ -1,6 +1,6 @@
 import { cached, cacheKey } from "./cache.js";
 import { parseTaskList } from "./records.js";
-import { runLedgerScript } from "./runner.js";
+import { failureOf, runLedgerScript } from "./runner.js";
 /**
  * LedgerFilter → skill 脚本参数（只拼调用方给了的；undefined 一律不拼，
  * 让脚本走自己的默认——插件不替脚本决定默认值）。
@@ -25,23 +25,6 @@ export function filterArgs(filter) {
         args.push("--until", filter.until);
     return args;
 }
-/**
- * 台账工作区探测：走 skill `root --json`（判据是「这个目录直接含 `ledger/`」，
- * 与脚本定位工作区根同一口径；有没有 `pool.json` 不影响）。
- *
- * 曾经的 `<path>/ledger/pool.json` 直查已废——布局知识只留 skill 一份。
- * 程序起不来时抛错（不静默把工作区藏掉）。
- */
-export async function hasLedger(workspacePath) {
-    const result = await runLedgerScript("root", [
-        "--dir",
-        workspacePath,
-        "--json",
-    ]);
-    if (!result.ok)
-        throw new Error(`台账根检测失败（${workspacePath}）：${result.error}`);
-    return result.data.root === true;
-}
 /**
  * 在办任务（包 `list --json`；结果过 records 入口校验后打上 workspace）。
  * 脚本失败 / 形状不符抛错——由 service 层捕获进 degraded，路由层转 500 + 人话，
@@ -56,7 +39,7 @@ export async function readTasks(workspace, filter = {}) {
             ...filterArgs(filter),
         ]);
         if (!result.ok)
-            throw new Error(`${workspace.title}: ${result.error}`);
+            throw failureOf(result, `${workspace.title}: `, workspace.id);
         return parseTaskList(result.data, workspace);
     });
 }
@@ -68,7 +51,7 @@ export async function readOwners(workspace) {
     return await cached(cacheKey(workspace.id, "owners", ""), async () => {
         const result = await runLedgerScript("owners", ["--repo", workspace.path, "--json"]);
         if (!result.ok)
-            throw new Error(`${workspace.title}: ${result.error}`);
+            throw failureOf(result, `${workspace.title}: `, workspace.id);
         const owners = Object.entries(result.data.owners ?? {}).map(([uuid, value]) => ({
             uuid,
             name: typeof value.name === "string" && value.name.trim() !== ""

package/dist/host/repositories/runner.d.ts

@@ -1,15 +1,33 @@
+/** 脚本绝对路径（界面上要写给用户复制的命令用；别在别处再拼一份）。 */
+export declare function scriptPath(): string;
+/**
+ * 脚本失败的统一出口：**没身份单独成类**（→ `LEDGER_IDENTITY_MISSING`），其余照旧是普通 Error。
+ * 各处别自己 `new Error(result.error)` —— 那样「没身份」就淹进「台账坏了」里，界面分不出来。
+ */
+export declare function failureOf(result: {
+    readonly error: string;
+    readonly identityMissing?: boolean;
+}, prefix?: string, workspaceId?: string | null): Error;
 export type LedgerScriptResult<T> = {
     ok: true;
     data: T;
 } | {
     ok: false;
     error: string;
+    /** 脚本退出码 4 = 这台机器还没有身份（`env.Current` 的专用码，文案不变）。 */
+    identityMissing?: boolean;
 };
 export interface RunOptions {
     /** 测试用：覆盖脚本路径。 */
     scriptPath?: string;
     /** 覆盖超时。 */
     timeoutMs?: number;
+    /**
+     * 过程步骤回调（写命令专用）：skill 每进一个阶段就在 stderr 打一行 `#step <key>`
+     * （`shell/render.go` 的 stepf，只有宿主设了 `TASK_LEDGER_STEPS=1` 才打）。
+     * 给了它才让 skill 打标记，读命令不传、不产生任何额外输出。
+     */
+    onStep?: (step: string) => void;
 }
 /**
  * 读命令：跑内嵌台账程序，收 stdout JSON。
@@ -21,3 +39,14 @@ export interface RunOptions {
  * @param opts.timeoutMs - 覆盖超时
  */
 export declare function runLedgerScript<T = unknown>(sub: string, args: readonly string[], opts?: RunOptions): Promise<LedgerScriptResult<T>>;
+/** 写命令结果：写动作只回人话（`shell/render.go` 的 RenderResult），**不认 --json** ⇒ 不解析 stdout。 */
+export type LedgerCommandResult = {
+    readonly ok: true;
+    readonly output: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly identityMissing?: boolean;
+};
+/** 写命令：认领 / 释放 / 结案这类改台账的动作走它（读命令走 `runLedgerScript`）。 */
+export declare function runLedgerCommand(sub: string, args: readonly string[], opts?: RunOptions): Promise<LedgerCommandResult>;