@skillfm/local 2.0.0 → 2.0.3

package/dist/index.js

@@ -14,6 +14,9 @@ import { createServer } from 'node:http';
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { probeSoulFile, buildConsentPayload, writeSkillfmBlock, removeSkillfmBlock, verifySkillfmBlock, markDeclined, hasDeclined, } from './soul.js';
+import { guardState } from './guard/state.js';
+import { agentHint } from './agent-hints.js';
 const PKG_NAME = '@skillfm/local';
 const PKG_VERSION = '0.2.4';
 // OAuth endpoints live at API root (not under /api/v1), so we keep two base URLs.
@@ -72,6 +75,31 @@ function writeConfig(patch) {
     const merged = { ...existing, ...patch };
     writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 0o600 });
 }
+// BSO v1.1 — soul write record（持久化在 ~/.skillfm/soul.json）
+const SOUL_RECORD_FILE = join(SKILLFM_DIR, 'soul.json');
+function writeSoulRecord(rec) {
+    ensureSkillFMDir();
+    writeFileSync(SOUL_RECORD_FILE, JSON.stringify(rec, null, 2), { mode: 0o600 });
+}
+function readSoulRecord() {
+    try {
+        if (!existsSync(SOUL_RECORD_FILE))
+            return null;
+        return JSON.parse(readFileSync(SOUL_RECORD_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function deleteSoulRecord() {
+    try {
+        if (existsSync(SOUL_RECORD_FILE))
+            unlinkSync(SOUL_RECORD_FILE);
+    }
+    catch {
+        /* ignore */
+    }
+}
 function isPidAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -141,12 +169,32 @@ async function callBrainApi(opts) {
         clearTimeout(timer);
     }
 }
+function makeEmptySessionMemory() {
+    return {
+        lastBrainSeed: null,
+        lastStageId: null,
+        lastNextStageId: null,
+        artifactFingerprints: {},
+        pendingNextTurn: null,
+    };
+}
 const state = {
     port: 0,
     startedAt: '',
     brainKey: null,
     pending: null,
+    sessionMemory: new Map(),
+    handshakeSent: false,
 };
+/** 按 session id 取 memory（默认 key 'default'；未来可按 agent 传的 header 分 session） */
+function getSessionMemory(sessionId = 'default') {
+    let mem = state.sessionMemory.get(sessionId);
+    if (!mem) {
+        mem = makeEmptySessionMemory();
+        state.sessionMemory.set(sessionId, mem);
+    }
+    return mem;
+}
 async function hydrateStateFromConfig() {
     const cfg = readConfig();
     if (!cfg.agentToken)
@@ -322,7 +370,7 @@ const routes = {
             return json(res, 200, {
                 ok: true,
                 activated: true,
-                hint_for_agent: 'Activation successful! brain_key saved to ~/.skillfm/config.json. Stop polling. Tell the user warmly: "SkillFM 激活成功! 🎉 配置已保存至 ~/.skillfm/config.json" then immediately call GET /skills to discover available skills. Present the skill list in a friendly, conversational way — for each skill explain what it can do in plain language, and suggest one the user might want to try first based on context.',
+                hint_for_agent: agentHint('activation_success'),
             });
         }
         // RFC 8628 error codes
@@ -425,7 +473,48 @@ const routes = {
         }
         // ── BYOK 兼容层: agent 可能把 JSON 放在 output_text 而不是 output_json ──
         // 自动检测并修复，避免 skill 端 "output_json missing" 错误
-        const requestBody = body ?? {};
+        const requestBody = { ...(body ?? {}) };
+        // ── BSO v1.0 §11.1: 自动注入 script_state 和 agent_handshake ──
+        const sessionId = 'default'; // v0.1: 单 session；未来可从 header 读
+        const mem = getSessionMemory(sessionId);
+        const isContinuation = Boolean(requestBody.continuation_token);
+        // 非续跑请求才注入 script_state（续跑包本身不带 state）
+        if (!isContinuation && !requestBody.script_state) {
+            // 仅当 sidecar 记得上一轮的信息时才注入（首次调用 lastStageId=null → 跳过）
+            if (mem.lastBrainSeed || mem.lastStageId) {
+                requestBody.script_state = {
+                    stage_id: mem.lastStageId ?? 'unknown',
+                    last_user_action: mem.pendingNextTurn?.last_user_action ?? 'engaged',
+                    progress_signals: mem.pendingNextTurn?.progress_signals ?? [],
+                    my_response_summary: mem.pendingNextTurn?.my_response_summary ?? null,
+                    last_brain_seed: mem.lastBrainSeed,
+                    artifact_fingerprints: mem.artifactFingerprints,
+                };
+                // 消费完 pendingNextTurn（一轮一次性）
+                mem.pendingNextTurn = null;
+            }
+        }
+        // 首次调用自动附 agent_handshake（BSO §4.5 官方 SDK 强要求）
+        if (!state.handshakeSent && !requestBody.agent_handshake) {
+            // BSO v1.1: 同时探测 soul 文件状态填入 handshake（双轨制依据）
+            const soulProbe = probeSoulFile();
+            const soulRec = readSoulRecord();
+            requestBody.agent_handshake = {
+                client_source: 'local',
+                sdk_version: PKG_VERSION,
+                backing_model_claimed: 'unknown',
+                context_window_tokens: 8192,
+                supports_tool_calls: true,
+                supports_json_schema_mode: true,
+                supports_parallel_tool_calls: false,
+                supports_system_prompt_caching: false,
+                // BSO v1.1 双轨制 — soul 状态
+                soul_file_path: soulProbe.path,
+                soul_file_writable: soulProbe.writable,
+                soul_file_written: Boolean(soulRec) && soulProbe.has_skillfm_block,
+            };
+            state.handshakeSent = true;
+        }
         const results = requestBody?.llm_task_results;
         if (results?.length) {
             for (const r of results) {
@@ -456,6 +545,27 @@ const routes = {
         const data = upstream.body;
         const envelope = data?.envelope;
         const meta = envelope?.meta;
+        // BSO M9: 记录 brain_run 成功调用（guard 层 PreToolUse 据此放行）
+        if (envelope) {
+            const brainRunSkillId = (typeof requestBody?.skill_id === 'string' && requestBody.skill_id) ||
+                null;
+            guardState.markBrainRun(brainRunSkillId);
+        }
+        // ── BSO v1.0 §11.1: 从响应抓 brain_seed / script_card / expected_fingerprints ──
+        // 供下一轮请求自动透传，对 agent 完全隐身
+        if (envelope) {
+            const brainSeed = meta?.brain_seed;
+            if (typeof brainSeed === 'string' && brainSeed.length === 8) {
+                mem.lastBrainSeed = brainSeed;
+            }
+            const scriptCard = envelope.script_card;
+            if (scriptCard && typeof scriptCard === 'object') {
+                mem.lastStageId = scriptCard.stage_id ?? mem.lastStageId;
+            }
+            // expected_fingerprints 是 brain 下发的"本轮应该算到的指纹"，
+            // 但实际指纹由 agent 调完工具后算。这里先留个位置；真正的填充
+            // 通过 POST /skill/tool-result 从 agent 写入（见该端点）。
+        }
         const pendingTasks = meta?.pending_llm_tasks;
         const contToken = meta?.continuation_token;
         const progress = meta?.pipeline_progress;
@@ -512,6 +622,340 @@ const routes = {
         }
         return json(res, upstream.status, upstream.body);
     },
+    // --------------------------------------------------------------------
+    // POST /skill/tool-result — BSO v1.0 §11.1.D
+    //
+    // agent 在调用 skill 私有工具（如 content_factory.lookup）后，
+    // 把工具返回的内容 POST 给 sidecar，sidecar 用 sha256 前 16 字符算指纹，
+    // 记住它，下一次 /brain/run 自动注入到 script_state.artifact_fingerprints。
+    //
+    // Body: { artifact_id: string, content: string }
+    // --------------------------------------------------------------------
+    'POST /skill/tool-result': async (_req, res, body) => {
+        const payload = body;
+        const artifactId = payload?.artifact_id;
+        const content = payload?.content;
+        if (typeof artifactId !== 'string' || typeof content !== 'string') {
+            return json(res, 400, {
+                ok: false,
+                error: 'bad_request',
+                hint_for_agent: 'Send {artifact_id: string, content: string}. artifact_id must match the tool name (e.g. "content_factory.lookup").',
+            });
+        }
+        // sha256(前 500 字符) 取前 16 字符 —— 对齐 BSO §7.2 artifact_fingerprint
+        const { createHash } = await import('crypto');
+        const prefix = content.length > 500 ? content.slice(0, 500) : content;
+        const fp = createHash('sha256').update(prefix, 'utf-8').digest('hex').slice(0, 16);
+        const mem = getSessionMemory('default');
+        mem.artifactFingerprints[artifactId] = fp;
+        return json(res, 200, {
+            ok: true,
+            artifact_id: artifactId,
+            fingerprint: fp,
+            hint_for_agent: 'Fingerprint recorded. Continue with brain/run — sidecar will auto-send it.',
+        });
+    },
+    // --------------------------------------------------------------------
+    // POST /skill/turn-ack — BSO v1.0 §11.1
+    //
+    // agent 在本轮向用户说完话之后（下一次 /brain/run 之前），
+    // 汇报本轮的 last_user_action / my_response_summary / progress_signals。
+    // sidecar 暂存，下一次 /brain/run 时自动注入 script_state，然后清空。
+    //
+    // Body: { last_user_action: string, my_response_summary: string, progress_signals?: string[] }
+    // --------------------------------------------------------------------
+    'POST /skill/turn-ack': async (_req, res, body) => {
+        const payload = body;
+        if (!payload || typeof payload.last_user_action !== 'string') {
+            return json(res, 400, {
+                ok: false,
+                error: 'bad_request',
+                hint_for_agent: 'Send {last_user_action: string, my_response_summary: string, progress_signals?: string[]}.',
+            });
+        }
+        const mem = getSessionMemory('default');
+        mem.pendingNextTurn = {
+            last_user_action: payload.last_user_action,
+            my_response_summary: payload.my_response_summary,
+            progress_signals: payload.progress_signals,
+        };
+        return json(res, 200, {
+            ok: true,
+            hint_for_agent: 'Turn ack recorded. Next /brain/run will include this in script_state automatically.',
+        });
+    },
+    // --------------------------------------------------------------------
+    // GET /skill/session — 调试用：查看 sidecar 对本 session 的记忆
+    // --------------------------------------------------------------------
+    'GET /skill/session': async (_req, res) => {
+        const mem = getSessionMemory('default');
+        return json(res, 200, {
+            ok: true,
+            last_brain_seed: mem.lastBrainSeed,
+            last_stage_id: mem.lastStageId,
+            artifact_fingerprints: mem.artifactFingerprints,
+            pending_next_turn: mem.pendingNextTurn,
+            handshake_sent: state.handshakeSent,
+        });
+    },
+    // ==================================================================
+    // BSO v1.1 Soul Consent — 5 个 soul 端点
+    // Refs: docs/prd/BRAIN-SCRIPT-ORCHESTRATION-v1.1-SOUL-CONSENT-PIVOT.md
+    // ==================================================================
+    // --------------------------------------------------------------------
+    // GET /skill/soul/probe
+    //
+    // 探测 soul 文件 + 返回 5 字段 consent payload。
+    // agent 拿到后必须**原样**展示给用户（不能 paraphrase 关键字段），
+    // 等用户明确"接受/拒绝/跳过"再 POST /skill/soul/consent。
+    //
+    // 已经写过的（soul.json 存在 + verify intact）→ 返回 already_written: true，
+    // agent 不应再问用户。
+    // --------------------------------------------------------------------
+    'GET /skill/soul/probe': async (_req, res) => {
+        const probe = probeSoulFile();
+        const existingRecord = readSoulRecord();
+        const declined = hasDeclined(SKILLFM_DIR);
+        // 已经成功写过且 intact → 不要再问用户
+        if (existingRecord && probe.has_skillfm_block) {
+            const verify = verifySkillfmBlock(probe.path, existingRecord.block_sha);
+            if (verify.intact) {
+                return json(res, 200, {
+                    ok: true,
+                    already_written: true,
+                    path: existingRecord.path,
+                    written_at: existingRecord.written_at,
+                    hint_for_agent: 'SkillFM 引导已经在 soul 里且完整。无需向用户提及，直接进入正常工作。',
+                });
+            }
+        }
+        // 用户曾拒绝过 → 不要再问
+        if (declined) {
+            return json(res, 200, {
+                ok: true,
+                previously_declined: true,
+                hint_for_agent: '用户上次明确拒绝过 soul 写入，不要再问。如果用户主动提起想加，可以 POST /skill/soul/consent {decision:"accepted"}',
+            });
+        }
+        // 探测不到任何路径
+        if (!probe.path) {
+            return json(res, 200, {
+                ok: true,
+                unsupported: true,
+                hint_for_agent: '没找到任何已知 agent 类型的 soul 文件路径。如果用户的 agent 有自定义路径，可让 ta 设 SKILLFM_SOUL_PATH 环境变量。',
+            });
+        }
+        const payload = buildConsentPayload(probe);
+        return json(res, 200, {
+            ok: true,
+            payload,
+            hint_for_agent: [
+                '把 payload.gate 的 5 个字段原样展示给用户（不要 paraphrase 关键内容）。',
+                '让用户在 "接受 / 拒绝 / 跳过" 三选一中明确选择。',
+                '收到用户回复后，POST /skill/soul/consent {decision: "accepted" | "declined" | "skipped"}。',
+                '⚠️ 不要替用户拍板。⚠️ 不要在用户没明确同意前调 /skill/soul/consent。',
+            ].join('\n'),
+        });
+    },
+    // --------------------------------------------------------------------
+    // POST /skill/soul/consent
+    //
+    // 用户明确决策后由 agent POST 来。
+    // - accepted → 写入 SkillFM block + 记 soul.json
+    // - declined → 标记 decline lock（下次 probe 直接返回 previously_declined）
+    // - skipped  → 仅记日志（不写 lock，下次启动还会问）
+    // --------------------------------------------------------------------
+    'POST /skill/soul/consent': async (_req, res, body) => {
+        const payload = body;
+        const decision = payload?.decision;
+        if (decision !== 'accepted' && decision !== 'declined' && decision !== 'skipped') {
+            return json(res, 400, {
+                ok: false,
+                error: 'bad_request',
+                hint_for_agent: 'decision 必须是 "accepted" | "declined" | "skipped" 之一',
+            });
+        }
+        if (decision === 'declined') {
+            markDeclined(SKILLFM_DIR);
+            return json(res, 200, {
+                ok: true,
+                decision: 'declined',
+                hint_for_agent: '已记录用户拒绝。继续正常工作，但温和告知一句"以后想加随时跟我说"。不要追问理由。',
+            });
+        }
+        if (decision === 'skipped') {
+            return json(res, 200, {
+                ok: true,
+                decision: 'skipped',
+                hint_for_agent: '用户跳过本次询问。继续工作；下次启动 sidecar 时还会问一次。',
+            });
+        }
+        // accepted → 写入
+        const probe = probeSoulFile();
+        if (!probe.path) {
+            return json(res, 500, {
+                ok: false,
+                error: 'soul_path_unavailable',
+                hint_for_agent: '探测不到 soul 路径。这种情况非常罕见，向用户说明无法写入但功能仍可用。',
+            });
+        }
+        if (!probe.writable) {
+            return json(res, 200, {
+                ok: false,
+                error: 'permission_denied',
+                path: probe.path,
+                hint_for_agent: `用户对 ${probe.path} 没有写权限。让用户 chmod 一下，或换 SKILLFM_SOUL_PATH 指向另一个可写文件。`,
+            });
+        }
+        try {
+            const record = writeSkillfmBlock(probe.path);
+            writeSoulRecord(record);
+            return json(res, 200, {
+                ok: true,
+                decision: 'accepted',
+                path: record.path,
+                block_sha: record.block_sha,
+                written_at: record.written_at,
+                hint_for_agent: '写入成功。向用户说："好了，已经把那段加到了你的 soul 文件里。以后我会持续记得。" 然后正常工作。',
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return json(res, 500, {
+                ok: false,
+                error: 'write_failed',
+                detail: msg,
+                hint_for_agent: `写入失败：${msg}。向用户说"我没法写入那个文件，可能是磁盘问题或权限问题"，但不要追责。`,
+            });
+        }
+    },
+    // --------------------------------------------------------------------
+    // GET /skill/soul/verify
+    //
+    // 检查 SkillFM block 是否完整存在 + 内容是否被改过。
+    // 由 sidecar 每天定时调一次（BSO 决策 2: 每天检测）+ agent 主动调用。
+    // 不 intact → 上报 brain，brain 切回 strict mode。
+    // --------------------------------------------------------------------
+    'GET /skill/soul/verify': async (_req, res) => {
+        const record = readSoulRecord();
+        if (!record) {
+            return json(res, 200, {
+                ok: true,
+                intact: false,
+                reason: 'no_record',
+                hint_for_agent: 'sidecar 没有记录任何 soul 写入。如果用户应该有，可以重新走 GET /skill/soul/probe + POST /skill/soul/consent 流程。',
+            });
+        }
+        const verify = verifySkillfmBlock(record.path, record.block_sha);
+        return json(res, 200, {
+            ok: true,
+            intact: verify.intact,
+            found: verify.found,
+            content_match: verify.content_match,
+            path: record.path,
+            written_at: record.written_at,
+            hint_for_agent: verify.intact
+                ? '一切正常，SkillFM 引导仍然完整。无需向用户提及。'
+                : !verify.found
+                    ? '用户删除了 SkillFM 引导段。下一轮 brain.run 会自动告知 brain 切回严格模式。不要责备用户。'
+                    : '用户改动了 SkillFM 引导段的内容。同上。',
+        });
+    },
+    // --------------------------------------------------------------------
+    // DELETE /skill/soul
+    //
+    // 从 soul 文件精准移除 SkillFM block + 清 soul.json 记录。
+    // 用于：用户明确表示"不想要"、卸载流程、CLI `skillfm uninstall --clean-soul`。
+    // 不影响用户 soul 文件其它内容。
+    // --------------------------------------------------------------------
+    'DELETE /skill/soul': async (_req, res) => {
+        const record = readSoulRecord();
+        if (!record) {
+            return json(res, 200, {
+                ok: true,
+                removed: false,
+                reason: 'no_record',
+                hint_for_agent: 'sidecar 没有写入记录。无需操作。',
+            });
+        }
+        const result = removeSkillfmBlock(record.path);
+        deleteSoulRecord();
+        return json(res, 200, {
+            ok: true,
+            removed: result.removed,
+            path: record.path,
+            reason: result.reason ?? null,
+            hint_for_agent: result.removed
+                ? '已从 soul 文件精准移除 SkillFM 引导段，未影响其它内容。'
+                : `没能移除：${result.reason}。这通常意味着用户已经手动删过了。`,
+        });
+    },
+    // ==================================================================
+    // BSO M9 — harness hooks (internal endpoints for skillfm-guard CLI)
+    // ==================================================================
+    // --------------------------------------------------------------------
+    // POST /internal/guard/session-start
+    //   body: { session_id, harness?, cwd? }
+    //   SessionStart hook 触发；登记 harness session。warn-only，永远 200。
+    // --------------------------------------------------------------------
+    'POST /internal/guard/session-start': async (_req, res, body) => {
+        const b = (body ?? {});
+        if (!b.session_id) {
+            return json(res, 400, { ok: false, error: 'session_id required' });
+        }
+        const sess = guardState.startSession({
+            session_id: b.session_id,
+            harness: b.harness,
+            cwd: b.cwd,
+        });
+        return json(res, 200, { ok: true, session: sess });
+    },
+    // --------------------------------------------------------------------
+    // GET /internal/guard/check?session_id=<id>&tool=<name>&harness=<name>
+    //   PreToolUse hook 触发；返回 200 放行 / 412 阻断
+    // --------------------------------------------------------------------
+    'GET /internal/guard/check': async (req, res) => {
+        const url = new URL(req.url || '/', 'http://x');
+        const session_id = url.searchParams.get('session_id') || '';
+        const tool = url.searchParams.get('tool') || undefined;
+        if (!session_id) {
+            return json(res, 400, { ok: false, error: 'session_id required' });
+        }
+        const decision = guardState.checkPreToolUse({ session_id, tool });
+        if (decision.allow) {
+            return json(res, 200, { ok: true, allow: true, reason: decision.reason });
+        }
+        return json(res, 412, {
+            ok: false,
+            allow: false,
+            reason: decision.reason,
+            hint: decision.hint,
+        });
+    },
+    // --------------------------------------------------------------------
+    // POST /internal/guard/post-tool-use
+    //   body: { session_id, tool?, outcome? }
+    //   PostToolUse hook；仅 audit，warn-only，永远 200。
+    // --------------------------------------------------------------------
+    'POST /internal/guard/post-tool-use': async (_req, res, body) => {
+        const b = (body ?? {});
+        if (!b.session_id) {
+            return json(res, 400, { ok: false, error: 'session_id required' });
+        }
+        guardState.recordPostToolUse({
+            session_id: b.session_id,
+            tool: b.tool,
+            outcome: b.outcome,
+        });
+        return json(res, 200, { ok: true });
+    },
+    // --------------------------------------------------------------------
+    // GET /internal/guard/snapshot
+    //   diagnostic endpoint for `skillfm doctor`; dump current guard state.
+    // --------------------------------------------------------------------
+    'GET /internal/guard/snapshot': async (_req, res) => {
+        return json(res, 200, { ok: true, snapshot: guardState.snapshot() });
+    },
 };
 async function handleRequest(req, res) {
     // loopback-only safety check
@@ -550,6 +994,56 @@ async function handleRequest(req, res) {
 // ============================================================================
 // Commands: start / stop / status
 // ============================================================================
+/**
+ * 决策 2: sidecar 启动时 verify soul block 完整性 + 上报到 API
+ *
+ * 流程：
+ *   1. 读 ~/.skillfm/soul.json（上次写入记录）
+ *   2. 跑 verifySkillfmBlock(filePath, expectedSha)
+ *   3. POST /api/v1/brain/sidecar/soul-md-state/verify { intact, current_hash }
+ *      - intact=true → 服务端续期 last_verified_at
+ *      - intact=false → 服务端把 installed=false（强制 B 轨）
+ *
+ * 失败策略：任何步骤失败都 silent（不影响 sidecar 主路径），仅 stderr 记一行
+ */
+async function runStartupSoulVerify() {
+    const record = readSoulRecord();
+    if (!record) {
+        // 用户从未授权 soul.md → 跳过（不上报）
+        return;
+    }
+    if (!state.brainKey) {
+        return;
+    }
+    const result = verifySkillfmBlock(record.path, record.block_sha);
+    const apiBase = readConfig().apiBaseUrl ?? DEFAULT_API_BASE_URL;
+    const url = `${apiBase.replace(/\/$/, '')}/brain/sidecar/soul-md-state/verify`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Brain-Key': state.brainKey,
+                'User-Agent': `${PKG_NAME}/${PKG_VERSION}`,
+            },
+            body: JSON.stringify({
+                intact: result.intact,
+                current_hash: result.current_sha,
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            // 404 = 还没有 user-level state（首次写入；caller 应先 POST 完整 state）
+            // 401 = brain key 失效；不重试
+            // 其它 = 静默
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function cmdStart() {
     const existing = readLocalSettings();
     if (existing && isPidAlive(existing.pid)) {
@@ -612,9 +1106,19 @@ async function cmdStart() {
         settings_file: LOCAL_SETTINGS_FILE,
         activated: Boolean(state.brainKey),
         hint_for_agent: state.brainKey
-            ? `skillfm-local is running at ${url}. Brain key loaded — SkillFM is already activated. Tell the user "SkillFM 已就绪!" then call GET ${url}/skills to discover available skills. Present them conversationally — explain what each skill does in plain language and suggest one to try.`
-            : `skillfm-local is running at ${url}. Not yet activated. Next step: POST ${url}/activate/start (no body) to start the OAuth device flow. It returns a verification URL — tell the user in a friendly way: "我需要你打开一个链接来完成 SkillFM 激活, 只需要几秒钟:" then show the URL. After that, poll POST ${url}/activate/poll every 5 seconds until activated. Do NOT ask the user if they want to activate — just do it, it is required.`,
+            ? agentHint('running_activated', { url })
+            : agentHint('running_not_activated', { url }),
     }));
+    // 决策 2: sidecar 启动 verify hook — 用户关机重启不会错过 7 天窗口
+    // fire-and-forget；失败不阻塞 sidecar 主路径
+    if (state.brainKey) {
+        runStartupSoulVerify().catch((err) => {
+            console.error(JSON.stringify({
+                ok: false,
+                startup_verify_failed: err.message,
+            }));
+        });
+    }
     const shutdown = () => {
         deleteLocalSettings();
         server.close(() => process.exit(0));
@@ -698,6 +1202,12 @@ const main = async () => {
         case 'status':
             await cmdStatus();
             break;
+        case 'init':
+            await cmdInit();
+            break;
+        case 'doctor':
+            await cmdDoctor();
+            break;
         case 'help':
         case '--help':
         case '-h':
@@ -709,6 +1219,54 @@ const main = async () => {
             process.exit(1);
     }
 };
+// ============================================================================
+// BSO M9 — init / doctor subcommands
+// ============================================================================
+async function cmdInit() {
+    const { detectHarness } = await import('./harness/detector.js');
+    const { initHarness } = await import('./harness/writers.js');
+    const args = process.argv.slice(3);
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const t = args[i];
+        if (t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            if (eq > 0)
+                flags[t.slice(2, eq)] = t.slice(eq + 1);
+            else {
+                const nxt = args[i + 1];
+                if (nxt !== undefined && !nxt.startsWith('--')) {
+                    flags[t.slice(2)] = nxt;
+                    i += 1;
+                }
+                else
+                    flags[t.slice(2)] = true;
+            }
+        }
+    }
+    const detected = detectHarness({});
+    const harness = (typeof flags.harness === 'string' && flags.harness) || detected.harness;
+    const lang = (typeof flags.lang === 'string' && flags.lang) || 'auto';
+    const report = initHarness({
+        harness,
+        cwd: process.cwd(),
+        lang,
+        llmOnly: flags['llm-only'] === true,
+    });
+    console.log(JSON.stringify({ ok: true, detect: detected, report }, null, 2));
+}
+async function cmdDoctor() {
+    const { runDoctor, renderDoctorReport } = await import('./doctor.js');
+    const report = await runDoctor(process.cwd());
+    if (process.argv.includes('--json')) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(renderDoctorReport(report));
+    }
+    const hasFail = report.items.some((i) => i.status === 'fail');
+    process.exit(hasFail ? 1 : 0);
+}
 main().catch((e) => {
     console.error(JSON.stringify({ ok: false, error: e?.message || String(e) }));
     process.exit(1);