@jeffusion/tianshu 0.0.0-stage → 0.1.1

package/docs/npm-distribution.md

@@ -0,0 +1,56 @@
+# npm 分发与 Codex 原生安装
+
+## 安装
+
+插件是 npmjs 上的 `@jeffusion/tianshu`。GitHub 只承载市场目录；Codex 根据目录直接获取 npm 包，不要求用户安装独立 CLI 或构建源码。
+
+```sh
+codex plugin marketplace add jeffusion/tianshu
+codex plugin add tianshu@jeffusion
+```
+
+要求 Node.js 24–26、npm、Python 3.12+ 与支持 npm 插件源的 Codex。当前验证范围是 macOS 桌面和 Linux/macOS 自动测试，Windows 尚未验收。npm 包不含安装脚本；插件生命周期由 Codex 管理。
+
+首次使用显式初始化业务台账，再检查本包的 MCP 和只读查询：
+
+```sh
+npx --yes @jeffusion/tianshu@0.1.1 init
+npx --yes @jeffusion/tianshu@0.1.1 doctor
+```
+
+已有配置只校验、不覆盖；指定不存在的 `--config` 会报错。doctor 检查当前 npm 包，不声称检查了 Codex 已安装版本或实际页面。重开 Codex、启用“天枢”、发送“@天枢 打开任务中心”，必要时展开到右侧。
+
+## 业务数据
+
+配置与台账在插件缓存之外。macOS 默认 `~/Library/Application Support/Tianshu`，Linux 默认 `$XDG_DATA_HOME/tianshu` 或 `~/.local/share/tianshu`；支持 `TIANSHU_HOME`。其中只有 `config.json` 与 `data/`，没有插件版本副本、安装状态或回滚日志。
+
+已有台账在默认 `config.json` 中填入原配置的 `sources` 与可选 `presentation_path`，保持数据库和证据的绝对路径；已有默认配置不要覆盖。也可以通过 `TIANSHU_CONFIG` 指定既有配置，但要确保启动 Codex 的环境和命令行相同。详见[配置说明](configuration.md)。插件查询缺失配置会报错，不自动建库。
+
+## 升级与卸载
+
+```sh
+codex plugin marketplace upgrade jeffusion
+codex plugin add tianshu@jeffusion
+# 卸载插件；业务台账和验收记录保留
+codex plugin remove tianshu@jeffusion
+# 不再需要这个市场时
+codex plugin marketplace remove jeffusion
+```
+
+市场将每次发行固定到明确的 npm 版本；刷新目录后使用 Codex 原生命令安装。版本选择和缓存由 Codex 负责；天枢不提供独立升级、回滚或卸载命令，也不自动清除数据。
+
+## 从旧的本地安装切换
+
+`0.1.0` 曾附带独立安装管理，已经移除。先保留既有 config.json、数据库和证据，再用 Codex 移除旧入口 `tianshu@tianshu` 与市场 `tianshu`（仅在该旧入口确实存在时），随后按上面的命令安装 `tianshu@jeffusion`。不要删除整个天枢数据目录，不运行旧版的安装命令；新的诊断不会读取旧安装状态。旧 releases/、marketplace/、installation.json、operation.json 与 lifecycle.lock 不再使用；确认旧安装已退出后可单独清理，保留 config.json、data/ 及用户证据。
+
+## 发布（维护者）
+
+日常测试不递增版本。正式 npm 版本不可覆盖，因此本次修正发布为 `0.1.1`，不覆盖 `0.1.0`。
+
+1. 同步 package.json、锁文件与 `.agents/plugins/marketplace.json` 的版本，PR 审查与 Linux/macOS CI 通过后合入 main。
+2. `npm run check` 验证实际 tarball 的文件边界、无源码依赖、无安装脚本、配置路由、MCP/页面资源和数据保全。`npm run test:native -- --local` 验证真实 Codex 宿主发现工具。
+3. 明确触发 `publish.yml`，输入版本；工作流构建 `dist/package`，打包该目录，经 `npm` 环境审批使用 OIDC 发布到 npmjs，并附来源证明。工程根包为 private，防止误发开发工程。
+4. 发布后运行 `npm run test:native`，验证真实 Codex 从 npmjs 安装、宿主加载四个 MCP 工具、doctor、卸载及台账保全；该测试仅使用临时 CODEX_HOME 和临时业务数据。
+5. 当前桌面客户端另验页面和“带到聊天”；命令行或 MCP 成功不能代替此项。
+
+可信发布绑定 GitHub `jeffusion/tianshu`、`publish.yml`、`npm` 环境。不要保存长期 npm token，也不要在聊天发送验证码。发布前的本地原生安装验收不等于 npmjs 安装已验收。

package/ledger/cli.py

@@ -0,0 +1,31 @@
+"""Resolve an allowlisted ledger, then invoke the unchanged transactional engine."""
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from config import load_config
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__,allow_abbrev=False)
+    parser.add_argument('--config')
+    parser.add_argument('--source',required=True)
+    parser.add_argument('command')
+    parser.add_argument('--input')
+    args=parser.parse_args()
+    try:
+        config=load_config(args.config)
+        source=next((s for s in config['sources'] if s['id']==args.source),None)
+        if not source:
+            raise ValueError('未配置的台账来源')
+        arguments=[args.command]+(['--input',args.input] if args.input is not None else [])
+        return subprocess.call([sys.executable,str(Path(__file__).with_name('coordinator.py')),
+                                '--db',source['path'],*arguments])
+    except (OSError,ValueError,TypeError) as error:
+        print(json.dumps({'ok':False,'error':str(error)},ensure_ascii=False))
+        return 1
+
+
+if __name__=='__main__':
+    sys.exit(main())

package/ledger/config.py

@@ -0,0 +1,44 @@
+"""One explicit configuration contract for the MCP projection and coordinator CLI."""
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def config_path(value=None):
+    selected=value or os.environ.get('TIANSHU_CONFIG')
+    home=os.environ.get('TIANSHU_HOME') or (
+        Path.home()/'Library/Application Support/Tianshu' if sys.platform=='darwin'
+        else Path(os.environ.get('XDG_DATA_HOME') or Path.home()/'.local/share')/'tianshu')
+    path=Path(selected) if selected else Path(os.path.normpath(str(Path(home)/'config.json')))
+    if not path.is_absolute():
+        raise ValueError('配置路径必须为绝对路径')
+    return path
+
+
+def load_config(value=None):
+    path=config_path(value)
+    raw=json.loads(path.read_text(encoding='utf-8'))
+    if not isinstance(raw,dict) or not isinstance(raw.get('sources'),list) or not raw['sources']:
+        raise ValueError('配置必须包含非空sources列表')
+    sources=[]
+    for source in raw['sources']:
+        if not isinstance(source,dict) or not isinstance(source.get('id'),str) or not re.fullmatch(r'[A-Za-z0-9_-]+',source['id']):
+            raise ValueError('无效来源ID')
+        if not isinstance(source.get('label'),str) or not source['label'].strip():
+            raise ValueError('来源label不能为空')
+        if not isinstance(source.get('path'),str) or not Path(source['path']).is_absolute():
+            raise ValueError('台账路径必须为绝对路径')
+        sources.append({k:source[k] for k in ('id','label','path')})
+    if len({s['id'] for s in sources})!=len(sources):
+        raise ValueError('来源ID重复')
+    result={'sources':sources}
+    presentation=raw.get('presentation_path')
+    if presentation is not None:
+        if not isinstance(presentation,str) or not Path(presentation).is_absolute():
+            raise ValueError('展示文案路径必须为绝对路径')
+        result['presentation']=json.loads(Path(presentation).read_text(encoding='utf-8'))
+        if not isinstance(result['presentation'],dict):
+            raise ValueError('展示文案必须为对象')
+    return result

package/ledger/coordinator.py

@@ -0,0 +1,393 @@
+#!/usr/bin/env python3
+"""Local ledger only. Never calls Codex, executes payloads, or grants permissions."""
+import argparse
+import json
+import os
+import sqlite3
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS tasks (
+ id TEXT PRIMARY KEY, revision INTEGER NOT NULL, state TEXT NOT NULL,
+ mandate_version INTEGER NOT NULL, data TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS mandates (
+ task_id TEXT NOT NULL REFERENCES tasks(id), version INTEGER NOT NULL,
+ data TEXT NOT NULL, PRIMARY KEY(task_id, version));
+CREATE TABLE IF NOT EXISTS dispatches (
+ id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES tasks(id),
+ mandate_version INTEGER NOT NULL, state TEXT NOT NULL, data TEXT NOT NULL);
+CREATE UNIQUE INDEX IF NOT EXISTS one_unresolved_dispatch ON dispatches(task_id)
+ WHERE state IN ('prepared','sent','uncertain');
+CREATE TABLE IF NOT EXISTS observations (
+ id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES tasks(id), data TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS events (
+ seq INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL REFERENCES tasks(id),
+ at TEXT NOT NULL, action TEXT NOT NULL, data TEXT NOT NULL);
+PRAGMA user_version=1;
+"""
+STATES = {
+ 'queued': {'running','waiting_human','waiting_external','failed','stopped'},
+ 'running': {'ready','waiting_human','waiting_external','failed','stopped'},
+ 'waiting_human': {'running','failed','stopped'},
+ 'waiting_external': {'running','failed','stopped'},
+ 'ready': {'accepted','running','waiting_human','failed','stopped'},
+ 'failed': {'running','stopped'}, 'accepted': set(), 'stopped': set(),
+}
+
+
+def encode(value):
+    return json.dumps(value, ensure_ascii=False, separators=(',', ':'))
+
+
+def require(condition, message):
+    if not condition:
+        raise ValueError(message)
+
+
+def string(data, key):
+    value = data.get(key)
+    require(isinstance(value, str) and bool(value.strip()), f'{key}: nonempty string required')
+    return value
+
+
+def strings(data, key):
+    value = data.get(key)
+    require(isinstance(value, list) and value and all(isinstance(v, str) and v.strip() for v in value),
+            f'{key}: nonempty string list required')
+    return value
+
+
+def event(db, task, action, data):
+    db.execute('INSERT INTO events(task_id,at,action,data) VALUES(?,?,?,?)',
+               (task, datetime.now(timezone.utc).isoformat(), action, encode(data)))
+
+
+def get_task(db, task_id, expected=None):
+    row = db.execute('SELECT * FROM tasks WHERE id=?', (task_id,)).fetchone()
+    require(row is not None, 'task not found')
+    task = dict(row)
+    task['data'] = json.loads(task['data'])
+    if expected is not None:
+        require(type(expected) is int and task['revision'] == expected, 'stale or invalid expected_revision; reread task')
+    return task
+
+
+def live(task):
+    require(task['state'] not in ('accepted','stopped'), 'terminal task; create a new task for new work')
+
+
+def save(db, task):
+    task['revision'] += 1
+    db.execute('UPDATE tasks SET revision=?,state=?,mandate_version=?,data=? WHERE id=?',
+               (task['revision'], task['state'], task['mandate_version'], encode(task['data']), task['id']))
+
+
+def mandate(data):
+    return {'allowed': strings(data, 'allowed'), 'forbidden': strings(data, 'forbidden'),
+            'authorization_source': string(data, 'authorization_source')}
+
+
+def dispatch(db, dispatch_id, task_id):
+    row = db.execute('SELECT * FROM dispatches WHERE id=? AND task_id=?', (dispatch_id, task_id)).fetchone()
+    require(row is not None, 'dispatch not found for this task')
+    result = dict(row)
+    result['data'] = json.loads(result['data'])
+    return result
+
+
+def deleted_task(db, task_id):
+    if not db.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_deletions'").fetchone():
+        return None
+    row = db.execute('SELECT receipt FROM task_deletions WHERE task_id=?', (task_id,)).fetchone()
+    return json.loads(row[0]) if row else None
+
+
+def preserve_rowid(db, table, allocate=False):
+    """Deletion must not rewind the row ordering used by existing incident boundaries."""
+    maximum = db.execute(f'SELECT COALESCE(MAX(rowid),0) FROM {table}').fetchone()[0]
+    if db.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_rowid_counters'").fetchone():
+        row = db.execute('SELECT high_water FROM task_rowid_counters WHERE name=?', (table,)).fetchone()
+        maximum = max(maximum, row[0] if row else 0)
+        value = maximum + int(allocate)
+        db.execute('INSERT INTO task_rowid_counters VALUES(?,?) ON CONFLICT(name) DO UPDATE SET high_water=excluded.high_water',
+                   (table, value))
+        return value
+    return maximum + int(allocate)
+
+
+def delete_task(db, data):
+    task_id = string(data, 'task_id')
+    require(type(data.get('expected_revision')) is int, 'expected_revision required for deletion')
+    string(data, 'reason')
+    string(data, 'authorization_source')
+    previous = deleted_task(db, task_id)
+    if previous:
+        require(previous['deleted_revision'] == data['expected_revision'], 'deleted revision mismatch')
+        return {**previous, 'already_deleted': True}
+    task = get_task(db, task_id, data['expected_revision'])
+    require(task['state'] in ('accepted','stopped'), 'only accepted or stopped tasks can be deleted')
+    require(not db.execute("SELECT 1 FROM dispatches WHERE task_id=? AND state IN ('prepared','sent','uncertain')", (task_id,)).fetchone(),
+            'reconcile unresolved dispatch before deletion')
+    incident = task['data'].get('incident')
+    require(not incident or incident['status'] == 'resolved', 'resolve open incident before deletion')
+    monitor = task['data'].get('monitor')
+    if monitor:
+        require(monitor.get('status') == 'stopped' and monitor.get('evidence'), 'stop monitor with evidence before deletion')
+    # This records the coordinator's actual external check, not a runtime authorization proof.
+    if task['data'].get('execution'):
+        string(data, 'execution_stop_evidence')
+    snapshot = run(db, 'task-show', {'task_id': task_id})
+    archive_id = str(uuid.uuid4())
+    receipt = {'task_id': task_id, 'deleted_revision': task['revision'], 'deleted': True,
+               'archive_id': archive_id, 'deleted_at': datetime.now(timezone.utc).isoformat(),
+               'already_deleted': False}
+    db.execute('''CREATE TABLE IF NOT EXISTS task_deletions (
+        task_id TEXT PRIMARY KEY, archive_id TEXT NOT NULL UNIQUE,
+        receipt TEXT NOT NULL, snapshot TEXT NOT NULL, request TEXT NOT NULL)''')
+    db.execute('INSERT INTO task_deletions VALUES(?,?,?,?,?)',
+               (task_id, archive_id, encode(receipt), encode(snapshot), encode(data)))
+    db.execute('CREATE TABLE IF NOT EXISTS task_rowid_counters (name TEXT PRIMARY KEY, high_water INTEGER NOT NULL)')
+    for table in ('observations','dispatches'):
+        preserve_rowid(db, table)
+    # Explicit ordering keeps foreign keys intact. Archive and removal share one transaction.
+    for table in ('events','observations','dispatches','mandates'):
+        db.execute(f'DELETE FROM {table} WHERE task_id=?', (task_id,))
+    db.execute('DELETE FROM tasks WHERE id=?', (task_id,))
+    return receipt
+
+
+def run(db, command, data):
+    if command == 'init':
+        return {'schema_version': 1}
+    if command == 'task-list':
+        return [get_task(db, r[0]) for r in db.execute('SELECT id FROM tasks ORDER BY id')]
+    task_id = string(data, 'task_id')
+    if command == 'task-delete':
+        return delete_task(db, data)
+    if command == 'task-create':
+        require(not deleted_task(db, task_id), 'deleted task id cannot be reused; use a new task id')
+        contents = {k: string(data, k) for k in ('objective','owner_thread_id','owner_host_id')}
+        contents['acceptance'] = strings(data, 'acceptance')
+        contents['project_id'] = data.get('project_id')
+        contents['execution'] = data.get('execution')
+        if contents['execution'] is not None:
+            require(isinstance(contents['execution'], dict), 'execution must be object')
+            string(contents['execution'], 'thread_id')
+            string(contents['execution'], 'host_id')
+        grant = mandate(data)
+        db.execute('INSERT INTO tasks VALUES(?,1,\'queued\',1,?)', (task_id, encode(contents)))
+        db.execute('INSERT INTO mandates VALUES(?,1,?)', (task_id, encode(grant)))
+        event(db, task_id, command, {'mandate_version': 1})
+        return get_task(db, task_id)
+    task = get_task(db, task_id)
+    if command == 'task-show':
+        task['mandates'] = [dict(r) | {'data': json.loads(r['data'])} for r in db.execute(
+            'SELECT * FROM mandates WHERE task_id=? ORDER BY version', (task_id,))]
+        for table in ('dispatches','observations','events'):
+            order = 'seq' if table == 'events' else 'rowid'
+            task[table] = [dict(r) | {'data': json.loads(r['data'])} for r in db.execute(
+                f'SELECT * FROM {table} WHERE task_id=? ORDER BY {order}', (task_id,))]
+        return task
+    require('expected_revision' in data, 'expected_revision required for mutations')
+    task = get_task(db, task_id, data['expected_revision'])
+    if command != 'observation-record' and not (command == 'monitor-record' and data.get('status') == 'stopped'):
+        live(task)
+    result = None
+    if command == 'mandate-revise':
+        require(not db.execute("SELECT 1 FROM dispatches WHERE task_id=? AND state IN ('prepared','sent','uncertain')", (task_id,)).fetchone(),
+                'reconcile unresolved dispatch before revising mandate')
+        grant = mandate(data)
+        task['mandate_version'] += 1
+        db.execute('INSERT INTO mandates VALUES(?,?,?)', (task_id, task['mandate_version'], encode(grant)))
+    elif command == 'dispatch-prepare':
+        require(task['state'] != 'failed', 'resume failed task explicitly before dispatch')
+        kind = string(data, 'kind')
+        require(kind in ('create_thread','send_message'), 'invalid kind')
+        require((kind == 'create_thread') == (task['data']['execution'] is None), 'kind conflicts with bound execution')
+        dispatch_id = string(data, 'dispatch_id')
+        payload = {'kind': kind, 'prompt': string(data, 'prompt'),
+                   'authorization_source': string(data, 'authorization_source'),
+                   'target': task['data']['execution'], 'project_id': task['data']['project_id']}
+        db.execute('INSERT INTO dispatches(rowid,id,task_id,mandate_version,state,data) VALUES(?,?,?,?,\'prepared\',?)',
+                   (preserve_rowid(db, 'dispatches', allocate=True), dispatch_id, task_id, task['mandate_version'], encode(payload)))
+        result = {'dispatch_id': dispatch_id}
+    elif command == 'dispatch-mark':
+        item = dispatch(db, string(data, 'dispatch_id'), task_id)
+        status = string(data, 'state')
+        moves = {'prepared': {'sent','uncertain','cancelled'}, 'sent': {'observed','uncertain'},
+                 'uncertain': {'sent','observed','cancelled'}}
+        require(status in moves.get(item['state'], set()), 'invalid dispatch transition')
+        require(item['mandate_version'] == task['mandate_version'], 'dispatch uses stale mandate')
+        receipt = data.get('receipt')
+        require(isinstance(receipt, dict) and receipt, 'receipt object required')
+        if status == 'sent':
+            string(receipt, 'thread_id')
+            string(receipt, 'host_id')
+            if task['data']['execution'] is None:
+                task['data']['execution'] = {k: receipt[k] for k in ('thread_id','host_id')}
+            else:
+                require(all(receipt[k] == task['data']['execution'][k] for k in ('thread_id','host_id')), 'receipt target mismatch')
+        if status == 'observed':
+            require(task['data']['execution'] is not None, 'bind actual receipt using sent first')
+            obs = db.execute('SELECT data FROM observations WHERE id=? AND task_id=?',
+                             (string(receipt, 'observation_id'), task_id)).fetchone()
+            require(obs is not None, 'observation required')
+            require(json.loads(obs[0]).get('dispatch_id') == item['id'], 'observation does not confirm this dispatch')
+        if status == 'cancelled':
+            string(receipt, 'reconciliation')
+        item['data']['receipt'] = receipt
+        db.execute('UPDATE dispatches SET state=?,data=? WHERE id=?', (status, encode(item['data']), item['id']))
+    elif command == 'observation-record':
+        require(task['data']['execution'] is not None, 'task has no execution binding')
+        require(data.get('host_id') == task['data']['execution']['host_id'] and
+                data.get('thread_id') == task['data']['execution']['thread_id'], 'observation target mismatch')
+        contents = {k: string(data,k) for k in ('host_id','thread_id','turn_id','summary')}
+        contents['evidence'] = strings(data, 'evidence')
+        contents['cursor'] = data.get('cursor')
+        contents['dispatch_id'] = data.get('dispatch_id')
+        if contents['dispatch_id']:
+            dispatch(db, contents['dispatch_id'], task_id)
+        observation_id = data.get('observation_id', str(uuid.uuid4()))
+        require(isinstance(observation_id, str) and observation_id.strip(), 'observation_id required')
+        db.execute('INSERT INTO observations(rowid,id,task_id,data) VALUES(?,?,?,?)',
+                   (preserve_rowid(db, 'observations', allocate=True), observation_id, task_id, encode(contents)))
+        task['data']['last_observation_id'] = observation_id
+        if 'cursor' in data:
+            require(data['cursor'] is None or isinstance(data['cursor'], str), 'cursor must be string or null')
+            task['data']['cursor'] = data['cursor']
+        result = {'observation_id': observation_id}
+    elif command == 'incident-record':
+        previous = task['data'].get('incident')
+        require(not previous or previous['status'] == 'resolved', 'resolve existing incident before recording another')
+        category = string(data, 'category')
+        require(category in ('direction_drift','authorization_gap','execution_failure','observation_unavailable'), 'invalid incident category')
+        incident_id = string(data, 'incident_id')
+        require(not previous or previous['id'] != incident_id, 'use a new incident id')
+        task['data']['incident'] = {'id': incident_id, 'category': category, 'status': 'open',
+            'summary': string(data, 'summary'), 'evidence': strings(data, 'evidence'),
+            'observation_boundary': db.execute('SELECT COALESCE(MAX(rowid),0) FROM observations').fetchone()[0],
+            'dispatch_boundary': db.execute('SELECT COALESCE(MAX(rowid),0) FROM dispatches').fetchone()[0],
+            'at': datetime.now(timezone.utc).isoformat()}
+    elif command == 'correction-link':
+        incident = task['data'].get('incident')
+        require(incident and incident['id'] == data.get('incident_id') and incident['status'] == 'open', 'open matching incident required')
+        item = dispatch(db, string(data, 'dispatch_id'), task_id)
+        dispatch_order = db.execute('SELECT rowid FROM dispatches WHERE id=?', (item['id'],)).fetchone()[0]
+        require(dispatch_order > incident['dispatch_boundary'], 'correction must be prepared after this incident')
+        require(item['data']['kind'] == 'send_message' and item['mandate_version'] == task['mandate_version'], 'correction must target current bound chat and mandate')
+        require(item['state'] != 'cancelled', 'cancelled correction cannot be linked')
+        old = incident.get('correction_dispatch_id')
+        old_item = dispatch(db, old, task_id) if old else None
+        if old_item and old != item['id']:
+            require(old_item['state'] in ('cancelled','observed'), 'reconcile existing correction before replacing')
+            old_order = db.execute('SELECT rowid FROM dispatches WHERE id=?', (old,)).fetchone()[0]
+            require(dispatch_order > old_order, 'replacement correction must be newer than current correction')
+            incident.setdefault('correction_history', []).append({'dispatch_id':old,
+                'reason':string(data,'replacement_reason'), 'evidence':strings(data,'replacement_evidence')})
+        incident['correction_dispatch_id'] = item['id']
+    elif command == 'incident-resolve':
+        incident = task['data'].get('incident')
+        require(incident and incident['id'] == data.get('incident_id') and incident['status'] == 'open', 'open matching incident required')
+        resolution = string(data, 'resolution')
+        require(resolution in ('corrected','dismissed','observation_restored'), 'invalid resolution')
+        require(not db.execute("SELECT 1 FROM dispatches WHERE task_id=? AND state IN ('prepared','sent','uncertain')", (task_id,)).fetchone(), 'reconcile unresolved dispatch before resolving')
+        if resolution != 'dismissed':
+            obs = db.execute('SELECT rowid,data FROM observations WHERE task_id=? AND id=?',
+                (task_id, string(data, 'observation_id'))).fetchone()
+            require(obs is not None, 'resolution requires observed evidence')
+            require(obs['rowid'] > incident['observation_boundary'], 'resolution requires a new observation after incident')
+            if resolution == 'corrected':
+                item = dispatch(db, incident.get('correction_dispatch_id'), task_id)
+                require(item['state'] == 'observed' and item['mandate_version'] == task['mandate_version'], 'correction must be read back under current mandate')
+                require(json.loads(obs['data']).get('dispatch_id') == item['id'], 'resolution observation must confirm linked correction')
+            else:
+                require(incident['category'] == 'observation_unavailable', 'observation restoration applies only to observation incidents')
+        incident.update({'status':'resolved', 'resolution':resolution,
+            'verified_by':string(data,'verified_by'), 'verification_evidence':strings(data,'verification_evidence'),
+            'resolved_at':datetime.now(timezone.utc).isoformat()})
+    elif command == 'monitor-record':
+        status = string(data, 'status')
+        require(status in ('watching','waiting_decision','stopped'), 'invalid monitor status')
+        if status == 'watching':
+            require(task['data']['execution'] is not None, 'monitor requires a bound execution chat')
+            require(not task['data'].get('incident') or task['data']['incident']['status'] == 'resolved', 'resolve open incident before resuming monitor')
+            string(data, 'automation_id')
+            string(data, 'authorization_source')
+        task['data']['monitor'] = {'status':status, 'automation_id':data.get('automation_id'),
+            'reason':string(data,'reason'), 'evidence':strings(data,'evidence'),
+            'at':datetime.now(timezone.utc).isoformat()}
+    elif command == 'task-transition':
+        status = string(data, 'state')
+        require(status in STATES[task['state']], 'invalid task transition')
+        string(data, 'reason')
+        if status in ('accepted','stopped'):
+            require(not db.execute("SELECT 1 FROM dispatches WHERE task_id=? AND state IN ('prepared','sent','uncertain')", (task_id,)).fetchone(),
+                    'reconcile dispatch before terminal transition')
+        if status == 'accepted':
+            require(not task['data'].get('incident') or task['data']['incident']['status'] == 'resolved', 'resolve open incident before acceptance')
+            require(task['data'].get('last_observation_id'), 'acceptance requires observation')
+            strings(data, 'verification_evidence')
+            string(data, 'verified_by')
+        if status == 'stopped':
+            string(data, 'stop_authorization_source')
+            string(data, 'execution_stop_evidence')
+        task['state'] = status
+    else:
+        raise ValueError('unknown command')
+    save(db, task)
+    event(db, task_id, command, data)
+    return {'task': task, **(result or {})}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--db', required=True, help='absolute database path; only init creates it')
+    parser.add_argument('command', choices=('init','task-create','task-list','task-show','mandate-revise',
+                       'dispatch-prepare','dispatch-mark','observation-record','task-transition',
+                       'incident-record','correction-link','incident-resolve','monitor-record','task-delete'))
+    parser.add_argument('--input', help='UTF-8 JSON object file; - reads stdin')
+    args = parser.parse_args()
+    try:
+        path = Path(args.db)
+        require(path.is_absolute(), '--db must be absolute')
+        data = {}
+        if args.input:
+            data = json.load(sys.stdin) if args.input == '-' else json.loads(Path(args.input).read_text(encoding='utf-8'))
+        require(isinstance(data, dict), 'input must be a JSON object')
+        os.umask(0o077)
+        if args.command == 'init':
+            require(not path.exists(), 'database already exists; init will not reset it')
+            path.parent.mkdir(parents=True, exist_ok=True)
+            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            os.close(fd)
+        else:
+            require(path.is_file(), 'database missing; use init explicitly')
+        db = sqlite3.connect(path.as_uri() + '?mode=rw', uri=True, timeout=5, isolation_level=None)
+        db.row_factory = sqlite3.Row
+        db.execute('PRAGMA foreign_keys=ON')
+        if args.command == 'init':
+            db.executescript('BEGIN IMMEDIATE;\n' + SCHEMA + '\nCOMMIT;')
+        require(db.execute('PRAGMA user_version').fetchone()[0] == 1, 'unsupported database schema')
+        try:
+            db.execute('BEGIN IMMEDIATE')
+            output = run(db, args.command, data)
+            db.execute('COMMIT')
+        except Exception:
+            if db.in_transaction:
+                db.execute('ROLLBACK')
+            raise
+        finally:
+            db.close()
+        print(encode({'ok': True, 'result': output}))
+        return 0
+    except (ValueError, OSError, sqlite3.Error, json.JSONDecodeError) as exc:
+        print(encode({'ok': False, 'error': str(exc)}))
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/ledger/read_ledger.py

@@ -0,0 +1,105 @@
+"""Read-only task projections. Paths come only from the operator's allowlist."""
+import argparse
+import json
+import sqlite3
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from config import load_config
+
+
+def text(value, maximum=3000):
+    return value[:maximum] if isinstance(value, str) else ''
+
+
+def items(value):
+    return [text(v) for v in value[:20] if isinstance(v, str)] if isinstance(value, list) else []
+
+
+def read_source(source):
+    path = Path(source['path'])
+    if not path.is_absolute() or not path.is_file():
+        raise ValueError('台账不存在')
+    db = sqlite3.connect(path.as_uri() + '?mode=ro', uri=True, timeout=2)
+    db.row_factory = sqlite3.Row
+    try:
+        db.execute('PRAGMA query_only=ON')
+        db.execute('BEGIN')
+        if db.execute('PRAGMA user_version').fetchone()[0] != 1:
+            raise ValueError('不支持的台账版本')
+        rows = db.execute('SELECT * FROM tasks ORDER BY rowid DESC LIMIT 200').fetchall()
+        result = []
+        for row in rows:
+            data = json.loads(row['data'])
+            grant = db.execute('SELECT data FROM mandates WHERE task_id=? AND version=?',
+                               (row['id'], row['mandate_version'])).fetchone()
+            grant = json.loads(grant[0]) if grant else {}
+            latest = db.execute('SELECT data FROM observations WHERE task_id=? ORDER BY rowid DESC LIMIT 1', (row['id'],)).fetchone()
+            observation = json.loads(latest[0]) if latest else {}
+            last_event = db.execute('SELECT at FROM events WHERE task_id=? ORDER BY seq DESC LIMIT 1', (row['id'],)).fetchone()
+            observation_event = db.execute("SELECT at FROM events WHERE task_id=? AND action='observation-record' ORDER BY seq DESC LIMIT 1", (row['id'],)).fetchone()
+            transitions = db.execute("SELECT at,data FROM events WHERE task_id=? AND action='task-transition' ORDER BY seq DESC LIMIT 6", (row['id'],)).fetchall()
+            verification = None
+            if row['state'] == 'accepted':
+                for transition in transitions:
+                    record = json.loads(transition['data'])
+                    if record.get('state') == 'accepted':
+                        verification = {'at': transition['at'], 'by': text(record.get('verified_by')),
+                                        'evidence': items(record.get('verification_evidence'))}
+                        break
+            execution = data.get('execution') or {}
+            raw_incident = data.get('incident') or {}
+            incident = {k: text(raw_incident.get(k)) for k in ('id','category','status','summary','at','resolution','resolved_at','verified_by','correction_dispatch_id')} if raw_incident else None
+            if incident:
+                incident['evidence'] = items(raw_incident.get('evidence'))
+                incident['verification_evidence'] = items(raw_incident.get('verification_evidence'))
+            raw_monitor = data.get('monitor') or {}
+            monitor = {k: text(raw_monitor.get(k)) for k in ('status','automation_id','reason','at')} if raw_monitor else None
+            result.append({
+                'key': source['id'] + ':' + row['id'], 'id': text(row['id'],200),
+                'source': source['id'], 'source_label': source['label'],
+                'objective': text(data.get('objective')), 'state': text(row['state'],50),
+                'revision': row['revision'], 'mandate_version': row['mandate_version'],
+                'host_id': text(execution.get('host_id'),200), 'thread_id': text(execution.get('thread_id'),200),
+                'acceptance': items(data.get('acceptance')), 'allowed': items(grant.get('allowed')),
+                'forbidden': items(grant.get('forbidden')), 'summary': text(observation.get('summary')),
+                'evidence': items(observation.get('evidence')), 'updated_at': last_event[0] if last_event else None,
+                'observed_at': observation_event[0] if observation_event else None,
+                'verification': verification,
+                'incident': incident, 'monitor': monitor,
+                'transitions': [{'at': e['at'], 'state': text(json.loads(e['data']).get('state'),50),
+                                 'reason': text(json.loads(e['data']).get('reason'))} for e in reversed(transitions)],
+            })
+        return result
+    finally:
+        db.close()
+
+
+def snapshot(config):
+    tasks, sources = [], []
+    for source in config['sources']:
+        try:
+            rows = read_source(source)
+            for task in rows:
+                display = config.get('presentation', {}).get(task['key'], {})
+                if display.get('revision') == task['revision']:
+                    task['display'] = {k: text(display.get(k), 1200) for k in
+                                       ('title', 'project', 'final_summary', 'final_at')}
+                    task['display']['evidence'] = items(display.get('evidence'))
+            tasks.extend(rows)
+            sources.append({'id': source['id'], 'label': source['label'], 'ok': True, 'count': len(rows)})
+        except (OSError, ValueError, sqlite3.Error, TypeError, KeyError):
+            sources.append({'id': source['id'], 'label': source['label'], 'ok': False,
+                            'error': '台账暂不可读，请检查本地配置或稍后刷新'})
+    return {'tasks': tasks, 'sources': sources, 'read_at': datetime.now(timezone.utc).isoformat(), 'readonly': True}
+
+
+if __name__ == '__main__':
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--config')
+    args=parser.parse_args()
+    try:
+        print(json.dumps(snapshot(load_config(args.config)),ensure_ascii=False))
+    except (OSError,ValueError,TypeError) as error:
+        print(json.dumps({'ok':False,'error':str(error)},ensure_ascii=False))
+        sys.exit(1)