@bububuger/spanory 0.1.15 → 0.1.18

package/dist/index.js

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
 // @ts-nocheck
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { chmod, copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { claudeCodeAdapter } from './runtime/claude/adapter.js';
 import { codexAdapter } from './runtime/codex/adapter.js';
 import { createCodexProxyServer } from './runtime/codex/proxy.js';
 import { openclawAdapter } from './runtime/openclaw/adapter.js';
 import { compileOtlp, parseHeaders, sendOtlp } from './otlp.js';
-import { loadUserEnv } from './env.js';
+import { loadUserEnv, resolveSpanoryEnvPath, resolveSpanoryHome } from './env.js';
+import { waitForFileMtimeToSettle } from './runtime/shared/file-settle.js';
 import { langfuseBackendAdapter } from '../../backend-langfuse/dist/index.js';
 import { evaluateRules, loadAlertRules, sendAlertWebhook } from './alert/evaluate.js';
-import { summarizeCache, loadExportedEvents, summarizeAgents, summarizeCommands, summarizeMcp, summarizeSessions, summarizeTools, summarizeTurnDiff, } from './report/aggregate.js';
+import { summarizeCache, loadExportedEvents, summarizeAgents, summarizeCommands, summarizeMcp, summarizeContext, summarizeSessions, summarizeTools, summarizeTurnDiff, } from './report/aggregate.js';
+import { loadIssueState, parsePendingTodoItems, resolveIssueStatePath, resolveTodoPath, saveIssueState, setIssueStatus, syncIssueState, } from './issue/state.js';
 const runtimeAdapters = {
     'claude-code': claudeCodeAdapter,
     codex: codexAdapter,
@@ -28,12 +32,61 @@ const OPENCODE_SPANORY_PLUGIN_ID = 'spanory-opencode-plugin';
 const DEFAULT_SETUP_RUNTIMES = ['claude-code', 'codex', 'openclaw', 'opencode'];
 const EMPTY_OUTPUT_RETRY_WINDOW_MS = 1000;
 const EMPTY_OUTPUT_RETRY_INTERVAL_MS = 120;
+const SPANORY_NPM_PACKAGE = '@bububuger/spanory';
+const HOOK_STDIN_IDLE_MS = 200;
+const HOOK_STDIN_TIMEOUT_MS = 1500;
 const CODEX_WATCH_DEFAULT_POLL_MS = 1200;
 const CODEX_WATCH_DEFAULT_SETTLE_MS = 250;
+const EXECUTION_ENTRY = (() => {
+    if (!('pkg' in process)) {
+        return fileURLToPath(import.meta.url);
+    }
+    const candidate = path.resolve(process.argv[1] ?? process.cwd());
+    try {
+        return realpathSync(candidate);
+    }
+    catch {
+        return candidate;
+    }
+})();
+const requireFromHere = createRequire(EXECUTION_ENTRY);
+const CLI_FILE_DIR = path.dirname(EXECUTION_ENTRY);
+const CLI_PACKAGE_DIR = path.resolve(CLI_FILE_DIR, '..');
+const DEFAULT_VERSION = '0.1.1';
+function readVersionFromPackageJson() {
+    const packageNameCandidates = ['@bububuger/spanory', '@spanory/cli'];
+    for (const packageName of packageNameCandidates) {
+        try {
+            const pkgJsonPath = requireFromHere.resolve(`${packageName}/package.json`);
+            const parsed = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+            const version = String(parsed?.version ?? '').trim();
+            if (version)
+                return version;
+        }
+        catch { }
+    }
+    const candidates = [
+        path.join(CLI_PACKAGE_DIR, 'package.json'),
+        path.resolve(process.cwd(), 'packages', 'cli', 'package.json'),
+    ];
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            const version = String(parsed?.version ?? '').trim();
+            if (version)
+                return version;
+        }
+        catch { }
+    }
+    return null;
+}
+const CLI_VERSION = process.env.SPANORY_VERSION ?? readVersionFromPackageJson() ?? DEFAULT_VERSION;
 function getResource() {
     return {
         serviceName: 'spanory',
-        serviceVersion: process.env.SPANORY_VERSION ?? '0.1.1',
+        serviceVersion: CLI_VERSION,
         environment: process.env.SPANORY_ENV ?? 'development',
     };
 }
@@ -64,11 +117,73 @@ function parseHookPayload(raw) {
         throw new Error('hook payload is not valid JSON');
     }
 }
+function redactSecretText(value) {
+    return String(value ?? '')
+        .replace(/(authorization\s*[:=]\s*)(basic|bearer)\s+[^\s"']+/ig, '$1[REDACTED]')
+        .replace(/\b(sk|pk)_[a-z0-9_-]{8,}\b/ig, '[REDACTED]');
+}
+function maskEndpoint(endpoint) {
+    const raw = String(endpoint ?? '').trim();
+    if (!raw)
+        return '';
+    try {
+        const url = new URL(raw);
+        return `${url.protocol}//${url.host}${url.pathname}`;
+    }
+    catch {
+        return redactSecretText(raw);
+    }
+}
 async function readStdinText() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
-    return Buffer.concat(chunks).toString('utf-8');
+    if (process.stdin.isTTY)
+        return '';
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let lastDataAt = Date.now();
+        let settled = false;
+        function done(error, value = '') {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(idleTimer);
+            clearTimeout(hardTimeout);
+            process.stdin.off('data', onData);
+            process.stdin.off('end', onEnd);
+            process.stdin.off('error', onError);
+            process.stdin.pause();
+            if (typeof process.stdin.unref === 'function') {
+                process.stdin.unref();
+            }
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        }
+        function onData(chunk) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            lastDataAt = Date.now();
+        }
+        function onEnd() {
+            done(null, Buffer.concat(chunks).toString('utf-8'));
+        }
+        function onError(error) {
+            done(error);
+        }
+        const idleTimer = setInterval(() => {
+            if (chunks.length === 0)
+                return;
+            if (Date.now() - lastDataAt >= HOOK_STDIN_IDLE_MS) {
+                done(null, Buffer.concat(chunks).toString('utf-8'));
+            }
+        }, 50);
+        const hardTimeout = setTimeout(() => {
+            done(new Error(`hook stdin read timeout after ${HOOK_STDIN_TIMEOUT_MS}ms`));
+        }, HOOK_STDIN_TIMEOUT_MS);
+        process.stdin.on('data', onData);
+        process.stdin.on('end', onEnd);
+        process.stdin.on('error', onError);
+        process.stdin.resume();
+    });
 }
 function fingerprintSession(context, events) {
     const hash = createHash('sha256');
@@ -177,6 +292,14 @@ function resolveRuntimeProjectRoot(runtimeName, explicitRuntimeHome) {
 function resolveRuntimeStateRoot(runtimeName, explicitRuntimeHome) {
     return path.join(resolveRuntimeHome(runtimeName, explicitRuntimeHome), 'state');
 }
+function resolveOpencodePluginStateRoot(runtimeHome) {
+    if (process.env.SPANORY_OPENCODE_STATE_DIR)
+        return process.env.SPANORY_OPENCODE_STATE_DIR;
+    if (runtimeHome || process.env.SPANORY_OPENCODE_HOME) {
+        return path.join(runtimeHome ?? resolveRuntimeHome('opencode'), 'state', 'spanory');
+    }
+    return path.join(resolveSpanoryHome(), 'opencode');
+}
 function resolveRuntimeExportDir(runtimeName, explicitRuntimeHome) {
     return path.join(resolveRuntimeStateRoot(runtimeName, explicitRuntimeHome), 'spanory-json');
 }
@@ -216,7 +339,7 @@ async function emitSession({ runtimeName, context, events, endpoint, headers, ex
     console.log(`runtime=${runtimeName} projectId=${context.projectId} sessionId=${context.sessionId} events=${events.length}`);
     if (endpoint) {
         await sendOtlp(endpoint, payload, headers);
-        console.log(`otlp=sent endpoint=${endpoint}`);
+        console.log(`otlp=sent endpoint=${maskEndpoint(endpoint)}`);
     }
     else {
         console.log('otlp=skipped endpoint=unset');
@@ -242,6 +365,23 @@ async function runHookMode(options) {
     if (!resolvedContext) {
         throw new Error('cannot resolve runtime context from hook payload; require session_id (or thread_id)');
     }
+    if (runtimeName === 'codex') {
+        const runtimeHome = resolveRuntimeHome(runtimeName, options.runtimeHome);
+        const transcriptPath = resolvedContext.transcriptPath
+            ?? (await listCodexSessions(runtimeHome)).find((session) => session.sessionId === resolvedContext.sessionId)?.transcriptPath;
+        if (transcriptPath) {
+            const settle = await waitForFileMtimeToSettle({
+                filePath: transcriptPath,
+                stableWindowMs: 350,
+                timeoutMs: 2500,
+                pollMs: 120,
+            });
+            resolvedContext.transcriptPath = transcriptPath;
+            if (!settle.settled) {
+                console.log(`hook=settle-timeout sessionId=${resolvedContext.sessionId} waitedMs=${settle.waitedMs}`);
+            }
+        }
+    }
     await runContextExportMode({
         runtimeName,
         context: resolvedContext,
@@ -565,13 +705,48 @@ function resolveOpenclawPluginDir() {
     if (process.env.SPANORY_OPENCLAW_PLUGIN_DIR) {
         return process.env.SPANORY_OPENCLAW_PLUGIN_DIR;
     }
-    return path.resolve(process.cwd(), 'packages/openclaw-plugin');
+    const candidates = [
+        resolveInstalledPackageDir('@bububuger/spanory-openclaw-plugin'),
+        path.resolve(CLI_PACKAGE_DIR, '..', 'openclaw-plugin'),
+        path.resolve(process.cwd(), 'packages/openclaw-plugin'),
+    ].filter(Boolean);
+    const hit = candidates.find((dir) => existsSync(path.join(dir, 'package.json')));
+    return hit ?? candidates[0] ?? path.resolve(process.cwd(), 'packages/openclaw-plugin');
 }
 function resolveOpencodePluginDir() {
     if (process.env.SPANORY_OPENCODE_PLUGIN_DIR) {
         return process.env.SPANORY_OPENCODE_PLUGIN_DIR;
     }
-    return path.resolve(process.cwd(), 'packages/opencode-plugin');
+    const pkgCandidate = process.pkg
+        ? path.resolve(path.dirname(process.execPath), '..', 'opencode-plugin')
+        : undefined;
+    const candidates = [
+        resolveInstalledPackageDir('@bububuger/spanory-opencode-plugin'),
+        pkgCandidate,
+        path.resolve(CLI_PACKAGE_DIR, '..', 'opencode-plugin'),
+        path.resolve(process.cwd(), 'packages/opencode-plugin'),
+    ].filter(Boolean);
+    const hit = candidates.find((dir) => existsSync(path.join(dir, 'package.json')));
+    return hit ?? candidates[0] ?? path.resolve(process.cwd(), 'packages/opencode-plugin');
+}
+function resolveInstalledPackageDir(packageName) {
+    try {
+        const pkgJsonPath = requireFromHere.resolve(`${packageName}/package.json`);
+        return path.dirname(pkgJsonPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolveOpencodePluginEntry(pluginDir) {
+    const explicitEntry = process.env.SPANORY_OPENCODE_PLUGIN_ENTRY;
+    if (explicitEntry) {
+        await stat(explicitEntry);
+        return explicitEntry;
+    }
+    const pluginEntry = path.join(pluginDir, 'dist', 'index.js');
+    await stat(pluginEntry);
+    return pluginEntry;
 }
 function resolveOpencodePluginInstallDir(runtimeHome) {
     return path.join(resolveRuntimeHome('opencode', runtimeHome), 'plugin');
@@ -613,7 +788,7 @@ async function runOpenclawPluginDoctor(runtimeHome) {
         id: 'otlp_endpoint',
         ok: Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT),
         detail: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
-            ? process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+            ? maskEndpoint(process.env.OTEL_EXPORTER_OTLP_ENDPOINT)
             : 'OTEL_EXPORTER_OTLP_ENDPOINT is unset',
     });
     const spoolDir = process.env.SPANORY_OPENCLAW_SPOOL_DIR
@@ -650,15 +825,32 @@ async function runOpencodePluginDoctor(runtimeHome) {
     catch {
         checks.push({ id: 'plugin_installed', ok: false, detail: `plugin loader missing: ${loaderFile}` });
     }
+    try {
+        const loaderUrl = pathToFileURL(loaderFile).href;
+        const mod = await import(loaderUrl);
+        const hasDefault = typeof mod.default === 'function' || typeof mod.SpanoryOpencodePlugin === 'function';
+        checks.push({
+            id: 'plugin_loadable',
+            ok: hasDefault,
+            detail: hasDefault ? 'plugin module loaded and exports a register function' : 'plugin module loaded but missing default export function',
+        });
+    }
+    catch (err) {
+        checks.push({
+            id: 'plugin_loadable',
+            ok: false,
+            detail: `plugin import failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
     checks.push({
         id: 'otlp_endpoint',
         ok: Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT),
         detail: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
-            ? process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+            ? maskEndpoint(process.env.OTEL_EXPORTER_OTLP_ENDPOINT)
             : 'OTEL_EXPORTER_OTLP_ENDPOINT is unset',
     });
     const spoolDir = process.env.SPANORY_OPENCODE_SPOOL_DIR
-        ?? path.join(resolveRuntimeStateRoot('opencode', runtimeHome), 'spanory', 'spool');
+        ?? path.join(resolveOpencodePluginStateRoot(runtimeHome), 'spool');
     try {
         await mkdir(spoolDir, { recursive: true });
         checks.push({ id: 'spool_writable', ok: true, detail: spoolDir });
@@ -666,8 +858,8 @@ async function runOpencodePluginDoctor(runtimeHome) {
     catch (err) {
         checks.push({ id: 'spool_writable', ok: false, detail: String(err) });
     }
-    const statusFile = path.join(resolveRuntimeStateRoot('opencode', runtimeHome), 'spanory', 'plugin-status.json');
-    const logFile = path.join(resolveRuntimeStateRoot('opencode', runtimeHome), 'spanory', 'plugin.log');
+    const statusFile = path.join(resolveOpencodePluginStateRoot(runtimeHome), 'plugin-status.json');
+    const logFile = path.join(resolveOpencodePluginStateRoot(runtimeHome), 'plugin.log');
     try {
         await mkdir(path.dirname(logFile), { recursive: true });
         checks.push({ id: 'opencode_plugin_log', ok: true, detail: logFile });
@@ -685,7 +877,7 @@ async function runOpencodePluginDoctor(runtimeHome) {
                 checks.push({
                     id: 'last_send_endpoint_configured',
                     ok: false,
-                    detail: 'last send skipped or failed to resolve OTLP endpoint in opencode process; check ~/.env and restart opencode',
+                    detail: `last send skipped or failed to resolve OTLP endpoint in opencode process; check ${resolveSpanoryEnvPath()} and restart opencode`,
                 });
             }
             else if (endpointConfigured === true) {
@@ -815,24 +1007,37 @@ function codexNotifyScriptContent({ spanoryBin, codexHome, exportDir, logFile })
         + 'set -euo pipefail\n'
         + 'payload="${1:-}"\n'
         + 'if [[ -z "$payload" ]] && [[ ! -t 0 ]]; then\n'
-        + '  payload="$(cat || true)"\n'
+        + '  IFS= read -r -t 0 payload || true\n'
         + 'fi\n'
         + 'if [[ -z "${payload//[$\'\\t\\r\\n \']/}" ]]; then\n'
         + `  echo "skip=empty-payload source=codex-notify args=$#" >> "${logFile}"\n`
         + '  exit 0\n'
         + 'fi\n'
+        + 'payload_file="$(mktemp "${TMPDIR:-/tmp}/spanory-codex-notify.XXXXXX")"\n'
+        + 'printf \'%s\' "$payload" > "$payload_file"\n'
         + `echo "$payload" | "${spanoryBin}" runtime codex hook \\\n`
         + '  --last-turn-only \\\n'
         + `  --runtime-home "${codexHome}" \\\n`
         + `  --export-json-dir "${exportDir}" \\\n`
-        + `  >> "${logFile}" 2>&1 || true\n`;
+        + `  >> "${logFile}" 2>&1 || true\n`
+        + '(\n'
+        + '  sleep 2\n'
+        + `  cat "$payload_file" | "${spanoryBin}" runtime codex hook \\\n`
+        + '    --last-turn-only \\\n'
+        + '    --force \\\n'
+        + `    --runtime-home "${codexHome}" \\\n`
+        + `    --export-json-dir "${exportDir}" \\\n`
+        + `    >> "${logFile}" 2>&1 || true\n`
+        + '  rm -f "$payload_file"\n'
+        + ') >/dev/null 2>&1 &\n';
 }
 async function applyCodexSetup({ homeRoot, spanoryBin, dryRun }) {
     const codexHome = path.join(homeRoot, '.codex');
+    const spanoryHome = process.env.SPANORY_HOME ?? path.join(homeRoot, '.spanory');
     const binDir = path.join(codexHome, 'bin');
     const stateDir = path.join(codexHome, 'state', 'spanory');
     const scriptPath = path.join(binDir, 'spanory-codex-notify.sh');
-    const logFile = path.join(codexHome, 'state', 'spanory-codex-hook.log');
+    const logFile = path.join(spanoryHome, 'logs', 'codex-notify.log');
     const configPath = path.join(codexHome, 'config.toml');
     const notifyScriptRef = scriptPath;
     const scriptContent = codexNotifyScriptContent({
@@ -865,6 +1070,7 @@ async function applyCodexSetup({ homeRoot, spanoryBin, dryRun }) {
     if (changed && !dryRun) {
         await mkdir(binDir, { recursive: true });
         await mkdir(stateDir, { recursive: true });
+        await mkdir(path.dirname(logFile), { recursive: true });
         if (configChanged) {
             configBackup = await backupIfExists(configPath);
             await writeFile(configPath, nextConfig, 'utf-8');
@@ -888,6 +1094,38 @@ function commandExists(command) {
     const result = runSystemCommand('which', [command], { env: process.env });
     return result.code === 0;
 }
+function detectUpgradePackageManager(userAgent = process.env.npm_config_user_agent) {
+    const token = String(userAgent ?? '').trim().split(/\s+/)[0] ?? '';
+    if (token.startsWith('tnpm/'))
+        return 'tnpm';
+    return 'npm';
+}
+function detectUpgradeScope() {
+    if (String(process.env.npm_config_global ?? '').trim() === 'true') {
+        return 'global';
+    }
+    const normalizedEntry = String(EXECUTION_ENTRY ?? '').replaceAll('\\', '/');
+    if (normalizedEntry.includes('/lib/node_modules/') || normalizedEntry.includes('/npm-global/')) {
+        return 'global';
+    }
+    if (normalizedEntry.includes('/node_modules/')) {
+        return 'local';
+    }
+    return 'global';
+}
+function resolveUpgradeInvocation(scope, manager) {
+    const selectedManager = manager === 'tnpm' ? 'tnpm' : 'npm';
+    const args = ['install'];
+    if (scope === 'global')
+        args.push('-g');
+    args.push(`${SPANORY_NPM_PACKAGE}@latest`);
+    return {
+        manager: selectedManager,
+        command: selectedManager,
+        args,
+        scope,
+    };
+}
 function openclawRuntimeHomeForSetup(homeRoot, explicitRuntimeHome) {
     return explicitRuntimeHome || path.join(homeRoot, '.openclaw');
 }
@@ -919,10 +1157,16 @@ function installOpenclawPlugin(runtimeHome) {
         enableStdout: enableResult.stdout.trim(),
     };
 }
-async function installOpencodePlugin(runtimeHome) {
-    const pluginDir = path.resolve(resolveOpencodePluginDir());
-    const pluginEntry = path.join(pluginDir, 'src', 'index.js');
-    await stat(pluginEntry);
+async function installOpencodePlugin(runtimeHome, pluginDirOverride) {
+    const pluginDir = path.resolve(pluginDirOverride ?? resolveOpencodePluginDir());
+    let pluginEntry;
+    try {
+        pluginEntry = await resolveOpencodePluginEntry(pluginDir);
+    }
+    catch {
+        throw new Error(`opencode plugin entry not found at ${path.join(pluginDir, 'dist', 'index.js')}. `
+            + 'build plugin first: npm run --workspace @bububuger/spanory-opencode-plugin build');
+    }
     const installDir = resolveOpencodePluginInstallDir(runtimeHome);
     const loaderFile = opencodePluginLoaderPath(runtimeHome);
     await mkdir(installDir, { recursive: true });
@@ -1477,18 +1721,8 @@ function registerRuntimeCommands(runtimeRoot, runtimeName) {
             .option('--plugin-dir <path>', 'Plugin directory path (default: packages/opencode-plugin)')
             .option('--runtime-home <path>', 'Override OpenCode runtime home (default: ~/.config/opencode)')
             .action(async (options) => {
-            const pluginDir = path.resolve(options.pluginDir ?? resolveOpencodePluginDir());
-            const pluginEntry = path.join(pluginDir, 'src', 'index.js');
-            await stat(pluginEntry);
-            const installDir = resolveOpencodePluginInstallDir(options.runtimeHome);
-            const loaderFile = opencodePluginLoaderPath(options.runtimeHome);
-            await mkdir(installDir, { recursive: true });
-            const importUrl = pathToFileURL(pluginEntry).href;
-            const loader = `import plugin from ${JSON.stringify(importUrl)};\n`
-                + 'export const SpanoryOpencodePlugin = plugin;\n'
-                + 'export default SpanoryOpencodePlugin;\n';
-            await writeFile(loaderFile, loader, 'utf-8');
-            console.log(`installed=${loaderFile}`);
+            const result = await installOpencodePlugin(options.runtimeHome, options.pluginDir);
+            console.log(`installed=${result.loaderFile}`);
         });
         plugin
             .command('uninstall')
@@ -1517,7 +1751,7 @@ program
     .description('Cross-runtime observability CLI for agent sessions')
     .showHelpAfterError()
     .showSuggestionAfterError(true)
-    .version('0.1.1');
+    .version(CLI_VERSION, '-v, --version');
 const runtime = program.command('runtime').description('Runtime-specific parsers and exporters');
 for (const runtimeName of ['claude-code', 'codex', 'openclaw', 'opencode']) {
     registerRuntimeCommands(runtime, runtimeName);
@@ -1571,6 +1805,14 @@ report
     const sessions = await loadExportedEvents(options.inputJson);
     console.log(JSON.stringify({ view: 'tool-summary', rows: summarizeTools(sessions) }, null, 2));
 });
+report
+    .command('context')
+    .description('Context observability summary per session')
+    .requiredOption('--input-json <path>', 'Path to exported JSON file or directory of JSON files')
+    .action(async (options) => {
+    const sessions = await loadExportedEvents(options.inputJson);
+    console.log(JSON.stringify({ view: 'context-summary', rows: summarizeContext(sessions) }, null, 2));
+});
 report
     .command('turn-diff')
     .description('Turn input diff summary view')
@@ -1613,9 +1855,66 @@ alert
         process.exitCode = 2;
     }
 });
+const issue = program.command('issue').description('Manage local issue status for automation巡检');
+issue
+    .command('sync')
+    .description('Sync pending items from todo.md into issue state file')
+    .option('--todo-file <path>', 'Path to todo markdown file (default: ./todo.md)')
+    .option('--state-file <path>', 'Path to issue state json file (default: ./docs/issues/state.json)')
+    .action(async (options) => {
+    const todoFile = resolveTodoPath(options.todoFile);
+    const stateFile = resolveIssueStatePath(options.stateFile);
+    const todoRaw = await readFile(todoFile, 'utf-8');
+    const pending = parsePendingTodoItems(todoRaw, 'todo.md');
+    const prev = await loadIssueState(stateFile);
+    const result = syncIssueState(prev, pending);
+    await saveIssueState(stateFile, result.state);
+    console.log(JSON.stringify({
+        stateFile,
+        todoFile,
+        pending: pending.length,
+        added: result.added,
+        reopened: result.reopened,
+        autoClosed: result.autoClosed,
+        total: result.state.issues.length,
+    }, null, 2));
+});
+issue
+    .command('list')
+    .description('List issues from state file')
+    .option('--state-file <path>', 'Path to issue state json file (default: ./docs/issues/state.json)')
+    .option('--status <status>', 'Filter by status: open,in_progress,blocked,done')
+    .action(async (options) => {
+    const stateFile = resolveIssueStatePath(options.stateFile);
+    const state = await loadIssueState(stateFile);
+    const statusFilter = options.status ? String(options.status).trim() : '';
+    const rows = statusFilter
+        ? state.issues.filter((item) => item.status === statusFilter)
+        : state.issues;
+    console.log(JSON.stringify({ stateFile, total: rows.length, issues: rows }, null, 2));
+});
+issue
+    .command('set-status')
+    .description('Update one issue status in state file')
+    .requiredOption('--id <id>', 'Issue id, e.g. T2')
+    .requiredOption('--status <status>', 'Target status: open|in_progress|blocked|done')
+    .option('--note <text>', 'Optional status note')
+    .option('--state-file <path>', 'Path to issue state json file (default: ./docs/issues/state.json)')
+    .action(async (options) => {
+    const stateFile = resolveIssueStatePath(options.stateFile);
+    const prev = await loadIssueState(stateFile);
+    const next = setIssueStatus(prev, {
+        id: options.id,
+        status: options.status,
+        note: options.note,
+    });
+    await saveIssueState(stateFile, next);
+    const issueItem = next.issues.find((item) => item.id === options.id);
+    console.log(JSON.stringify({ stateFile, issue: issueItem }, null, 2));
+});
 program
     .command('hook')
-    .description('Minimal hook entrypoint (defaults to runtime payload + ~/.env + default export dir)')
+    .description('Minimal hook entrypoint (defaults to runtime payload + ~/.spanory/.env + default export dir)')
     .option('--runtime <name>', 'Runtime name (default: SPANORY_HOOK_RUNTIME or claude-code)')
     .option('--runtime-home <path>', 'Override runtime home directory')
     .option('--endpoint <url>', 'OTLP HTTP endpoint (fallback: OTEL_EXPORTER_OTLP_ENDPOINT)')
@@ -1680,6 +1979,33 @@ setup
     if (!report.ok)
         process.exitCode = 2;
 });
+program
+    .command('upgrade')
+    .description('Upgrade spanory CLI from npm registry')
+    .option('--dry-run', 'Print upgrade command without executing', false)
+    .option('--manager <name>', 'Package manager override: npm|tnpm')
+    .option('--scope <scope>', 'Install scope override: global|local')
+    .action(async (options) => {
+    const manager = options.manager === 'tnpm' ? 'tnpm' : detectUpgradePackageManager();
+    const scope = options.scope === 'local' ? 'local' : options.scope === 'global' ? 'global' : detectUpgradeScope();
+    const invocation = resolveUpgradeInvocation(scope, manager);
+    if (options.dryRun) {
+        console.log(JSON.stringify({ dryRun: true, ...invocation }, null, 2));
+        return;
+    }
+    const result = runSystemCommand(invocation.command, invocation.args, { env: process.env });
+    const output = (result.stdout || result.stderr || '').trim();
+    if (result.code !== 0) {
+        console.error(output || result.error || 'upgrade failed');
+        process.exitCode = 2;
+        return;
+    }
+    console.log(JSON.stringify({
+        ok: true,
+        ...invocation,
+        output,
+    }, null, 2));
+});
 loadUserEnv()
     .then(() => program.parseAsync(process.argv))
     .catch((error) => {

package/dist/issue/state.d.ts

@@ -0,0 +1,39 @@
+export declare const ISSUE_STATUSES: readonly ["open", "in_progress", "blocked", "done"];
+export type IssueStatus = (typeof ISSUE_STATUSES)[number];
+export interface IssueItem {
+    id: string;
+    title: string;
+    source: string;
+    status: IssueStatus;
+    notes: string[];
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string;
+}
+export interface IssueState {
+    version: 1;
+    updatedAt: string;
+    issues: IssueItem[];
+}
+export interface PendingTodoItem {
+    id: string;
+    title: string;
+    source: string;
+}
+export declare function parsePendingTodoItems(todoContent: string, source?: string): PendingTodoItem[];
+export declare function syncIssueState(prev: IssueState, pending: PendingTodoItem[], now?: string): {
+    state: IssueState;
+    added: number;
+    reopened: number;
+    autoClosed: number;
+};
+export declare function setIssueStatus(prev: IssueState, input: {
+    id: string;
+    status: string;
+    note?: string;
+}, now?: string): IssueState;
+export declare function createEmptyIssueState(now?: string): IssueState;
+export declare function loadIssueState(filePath: string): Promise<IssueState>;
+export declare function saveIssueState(filePath: string, state: IssueState): Promise<void>;
+export declare function resolveIssueStatePath(input?: string): string;
+export declare function resolveTodoPath(input?: string): string;