@team-semicolon/semo-cli 4.15.0 → 4.16.0

package/dist/commands/agent-flush.d.ts

@@ -0,0 +1,13 @@
+/**
+ * semo agent-flush — 서브에이전트 종료 시 KB/commitments flush
+ *
+ * SubagentStop 훅에서 호출. stdin으로 session context를 받아:
+ * 1. 해당 세션의 active commitment → done 처리
+ * 2. bot_sessions 상태 → terminated
+ *
+ * 사용법:
+ *   npx semo agent-flush --bot semiclaw
+ *   (stdin으로 { session_id, transcript_path } JSON 수신)
+ */
+import { Command } from 'commander';
+export declare function registerAgentFlushCommands(program: Command): void;

package/dist/commands/agent-flush.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * semo agent-flush — 서브에이전트 종료 시 KB/commitments flush
+ *
+ * SubagentStop 훅에서 호출. stdin으로 session context를 받아:
+ * 1. 해당 세션의 active commitment → done 처리
+ * 2. bot_sessions 상태 → terminated
+ *
+ * 사용법:
+ *   npx semo agent-flush --bot semiclaw
+ *   (stdin으로 { session_id, transcript_path } JSON 수신)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgentFlushCommands = registerAgentFlushCommands;
+const database_1 = require("../database");
+function registerAgentFlushCommands(program) {
+    program
+        .command('agent-flush')
+        .description('서브에이전트 종료 시 commitment/session flush')
+        .requiredOption('--bot <botId>', '봇 ID')
+        .action(async (options) => {
+        const { bot: botId } = options;
+        // stdin에서 session context 읽기 (SubagentStop 훅이 전달)
+        let sessionId = '';
+        try {
+            const input = await readStdin();
+            if (input) {
+                const parsed = JSON.parse(input);
+                sessionId = parsed.session_id || '';
+            }
+        }
+        catch {
+            // stdin 없거나 파싱 실패 — 무시하고 진행
+        }
+        const connected = await (0, database_1.isDbConnected)();
+        if (!connected) {
+            process.exit(0); // DB 없으면 조용히 종료 (훅이 세션 블로킹하지 않도록)
+        }
+        try {
+            const pool = (0, database_1.getPool)();
+            // 1. 해당 봇의 active/pending commitment → done 처리
+            const commitResult = await pool.query(`UPDATE semo.bot_commitments
+           SET status = 'done'
+           WHERE bot_id = $1
+             AND status IN ('pending', 'active')
+             AND ($2 = '' OR assigned_session = $2)
+           RETURNING id, title`, [botId, sessionId]);
+            for (const row of commitResult.rows) {
+                process.stderr.write(`[agent-flush] commitment done: ${row.id} — ${row.title}\n`);
+            }
+            // 2. bot_sessions 상태 → terminated
+            if (sessionId) {
+                await pool.query(`UPDATE semo.bot_sessions
+             SET status = 'terminated', ended_at = NOW()
+             WHERE session_key = $1 AND bot_id = $2`, [sessionId, botId]);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[agent-flush] error: ${err}\n`);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (data += chunk));
+        process.stdin.on('end', () => resolve(data.trim()));
+        // stdin이 즉시 닫혀있으면 빈 문자열 반환
+        setTimeout(() => resolve(data.trim()), 500);
+    });
+}

package/dist/commands/commitments.d.ts

@@ -4,5 +4,5 @@
  * 봇이 "~하겠습니다" 약속 후 세션 종료되어도 추적 가능하도록
  * semo.bot_commitments 테이블에 기록하고, 워치독이 overdue/stale 감지.
  */
-import { Command } from "commander";
+import { Command } from 'commander';
 export declare function registerCommitmentsCommands(program: Command): void;

package/dist/commands/commitments.js

@@ -24,11 +24,11 @@ function parseDeadline(input) {
         const value = parseInt(match[1]);
         const unit = match[2];
         const now = new Date();
-        if (unit === "m")
+        if (unit === 'm')
             now.setMinutes(now.getMinutes() + value);
-        else if (unit === "h")
+        else if (unit === 'h')
             now.setHours(now.getHours() + value);
-        else if (unit === "d")
+        else if (unit === 'd')
             now.setDate(now.getDate() + value);
         return now.toISOString();
     }
@@ -38,23 +38,23 @@ function parseDeadline(input) {
 // ─── Command registration ───────────────────────────────────────────────────
 function registerCommitmentsCommands(program) {
     const cmd = program
-        .command("commitments")
-        .description("봇 약속 추적 (Durable Commitment Tracking)");
+        .command('commitments')
+        .description('봇 약속 추적 (Durable Commitment Tracking)');
     // ── semo commitments create ────────────────────────────────────────────────
     cmd
-        .command("create")
-        .description("새 약속 등록")
-        .requiredOption("--bot-id <id>", "봇 ID")
-        .requiredOption("--title <text>", "약속 제목")
-        .option("--description <text>", "상세 설명")
-        .option("--source-type <type>", "출처 (github-issue|slack|cron|manual)")
-        .option("--source-ref <ref>", "출처 참조 (issue URL, channel:thread)")
-        .option("--deadline <time>", "기한 (15m, 1h, 2d, 또는 ISO 문자열)")
-        .option("--steps <json>", "단계 JSON 배열 (예: \'[{\"label\":\"Step1\",\"done\":false}]\')")
+        .command('create')
+        .description('새 약속 등록')
+        .requiredOption('--bot-id <id>', '봇 ID')
+        .requiredOption('--title <text>', '약속 제목')
+        .option('--description <text>', '상세 설명')
+        .option('--source-type <type>', '출처 (github-issue|slack|cron|manual)')
+        .option('--source-ref <ref>', '출처 참조 (issue URL, channel:thread)')
+        .option('--deadline <time>', '기한 (15m, 1h, 2d, 또는 ISO 문자열)')
+        .option('--steps <json>', '단계 JSON 배열 (예: \'[{"label":"Step1","done":false}]\')')
         .action(async (options) => {
         const connected = await (0, database_1.isDbConnected)();
         if (!connected) {
-            console.error(chalk_1.default.red("❌ DB 연결 실패"));
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
             await (0, database_1.closeConnection)();
             process.exit(1);
         }
@@ -66,7 +66,7 @@ function registerCommitmentsCommands(program) {
                 steps = JSON.parse(options.steps);
             }
             catch {
-                console.error(chalk_1.default.red("❌ --steps JSON 파싱 실패"));
+                console.error(chalk_1.default.red('❌ --steps JSON 파싱 실패'));
                 await (0, database_1.closeConnection)();
                 process.exit(1);
             }
@@ -89,7 +89,12 @@ function registerCommitmentsCommands(program) {
             if (!options.sourceType) {
                 console.log(chalk_1.default.yellow(`⚠ source-type 미지정: 자동 검증 불가. --source-type 권장.`));
             }
-            console.log(JSON.stringify({ id, bot_id: options.botId, title: options.title, deadline_at: deadlineAt }));
+            console.log(JSON.stringify({
+                id,
+                bot_id: options.botId,
+                title: options.title,
+                deadline_at: deadlineAt,
+            }));
         }
         catch (err) {
             console.error(chalk_1.default.red(`❌ create 실패: ${err}`));
@@ -101,15 +106,15 @@ function registerCommitmentsCommands(program) {
     });
     // ── semo commitments update ────────────────────────────────────────────────
     cmd
-        .command("update <id>")
-        .description("진행 보고 (heartbeat, status, step 완료)")
-        .option("--heartbeat", "heartbeat 갱신")
-        .option("--status <status>", "상태 변경 (active|pending)")
-        .option("--step-done <label>", "특정 step을 완료 처리")
+        .command('update <id>')
+        .description('진행 보고 (heartbeat, status, step 완료)')
+        .option('--heartbeat', 'heartbeat 갱신')
+        .option('--status <status>', '상태 변경 (active|pending)')
+        .option('--step-done <label>', '특정 step을 완료 처리')
         .action(async (id, options) => {
         const connected = await (0, database_1.isDbConnected)();
         if (!connected) {
-            console.error(chalk_1.default.red("❌ DB 연결 실패"));
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
             await (0, database_1.closeConnection)();
             process.exit(1);
         }
@@ -123,7 +128,10 @@ function registerCommitmentsCommands(program) {
                 console.log(chalk_1.default.green(`✔ heartbeat updated: ${id}`));
             }
             if (options.status) {
-                await pool.query(`UPDATE semo.bot_commitments SET status = $1 WHERE id = $2`, [options.status, id]);
+                await pool.query(`UPDATE semo.bot_commitments SET status = $1 WHERE id = $2`, [
+                    options.status,
+                    id,
+                ]);
                 console.log(chalk_1.default.green(`✔ status → ${options.status}: ${id}`));
             }
             if (options.stepDone) {
@@ -151,12 +159,12 @@ function registerCommitmentsCommands(program) {
     });
     // ── semo commitments done ──────────────────────────────────────────────────
     cmd
-        .command("done <id>")
-        .description("약속 완료 처리")
+        .command('done <id>')
+        .description('약속 완료 처리')
         .action(async (id) => {
         const connected = await (0, database_1.isDbConnected)();
         if (!connected) {
-            console.error(chalk_1.default.red("❌ DB 연결 실패"));
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
             await (0, database_1.closeConnection)();
             process.exit(1);
         }
@@ -180,13 +188,13 @@ function registerCommitmentsCommands(program) {
     });
     // ── semo commitments fail ──────────────────────────────────────────────────
     cmd
-        .command("fail <id>")
-        .description("약속 실패 처리")
-        .option("--reason <text>", "실패 사유")
+        .command('fail <id>')
+        .description('약속 실패 처리')
+        .option('--reason <text>', '실패 사유')
         .action(async (id, options) => {
         const connected = await (0, database_1.isDbConnected)();
         if (!connected) {
-            console.error(chalk_1.default.red("❌ DB 연결 실패"));
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
             await (0, database_1.closeConnection)();
             process.exit(1);
         }
@@ -194,7 +202,7 @@ function registerCommitmentsCommands(program) {
             const pool = (0, database_1.getPool)();
             const metadataUpdate = options.reason
                 ? `, metadata = metadata || jsonb_build_object('fail_reason', $2::text)`
-                : "";
+                : '';
             const params = options.reason ? [id, options.reason] : [id];
             const result = await pool.query(`UPDATE semo.bot_commitments SET status = 'failed'${metadataUpdate} WHERE id = $1 AND status IN ('pending', 'active') RETURNING id`, params);
             if (result.rowCount === 0) {
@@ -214,16 +222,16 @@ function registerCommitmentsCommands(program) {
     });
     // ── semo commitments list ──────────────────────────────────────────────────
     cmd
-        .command("list")
-        .description("약속 목록 조회")
-        .option("--bot-id <id>", "특정 봇만")
-        .option("--status <status>", "상태 필터 (pending|active|done|failed|expired)")
-        .option("--limit <n>", "최대 조회 수", "20")
-        .option("--format <type>", "출력 형식 (table|json)", "table")
+        .command('list')
+        .description('약속 목록 조회')
+        .option('--bot-id <id>', '특정 봇만')
+        .option('--status <status>', '상태 필터 (pending|active|done|failed|expired)')
+        .option('--limit <n>', '최대 조회 수', '20')
+        .option('--format <type>', '출력 형식 (table|json)', 'table')
         .action(async (options) => {
         const connected = await (0, database_1.isDbConnected)();
         if (!connected) {
-            console.error(chalk_1.default.red("❌ DB 연결 실패"));
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
             await (0, database_1.closeConnection)();
             process.exit(1);
         }
@@ -240,7 +248,7 @@ function registerCommitmentsCommands(program) {
                 conditions.push(`status = $${paramIdx++}`);
                 params.push(options.status);
             }
-            const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+            const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
             params.push(parseInt(options.limit));
             const result = await pool.query(`SELECT id, bot_id, status, title, description, source_type, source_ref,
                   deadline_at::text, steps,
@@ -249,27 +257,31 @@ function registerCommitmentsCommands(program) {
            ${where}
            ORDER BY created_at DESC
            LIMIT $${paramIdx}`, params);
-            if (options.format === "json") {
+            if (options.format === 'json') {
                 console.log(JSON.stringify(result.rows, null, 2));
             }
             else {
-                console.log(chalk_1.default.cyan.bold("\n📋 Commitments\n"));
+                console.log(chalk_1.default.cyan.bold('\n📋 Commitments\n'));
                 if (result.rows.length === 0) {
-                    console.log(chalk_1.default.yellow("  약속 없음"));
+                    console.log(chalk_1.default.yellow('  약속 없음'));
                 }
                 else {
                     for (const c of result.rows) {
-                        const statusColor = c.status === "done" ? chalk_1.default.green :
-                            c.status === "failed" ? chalk_1.default.red :
-                                c.status === "expired" ? chalk_1.default.gray :
-                                    c.status === "active" ? chalk_1.default.cyan :
-                                        chalk_1.default.yellow;
+                        const statusColor = c.status === 'done'
+                            ? chalk_1.default.green
+                            : c.status === 'failed'
+                                ? chalk_1.default.red
+                                : c.status === 'expired'
+                                    ? chalk_1.default.gray
+                                    : c.status === 'active'
+                                        ? chalk_1.default.cyan
+                                        : chalk_1.default.yellow;
                         const deadline = c.deadline_at
-                            ? new Date(c.deadline_at).toLocaleString("ko-KR")
-                            : "-";
+                            ? new Date(c.deadline_at).toLocaleString('ko-KR')
+                            : '-';
                         const stepsInfo = Array.isArray(c.steps) && c.steps.length > 0
                             ? ` [${c.steps.filter((s) => s.done).length}/${c.steps.length}]`
-                            : "";
+                            : '';
                         console.log(`  ${statusColor(c.status.padEnd(8))} ` +
                             chalk_1.default.white(c.title.slice(0, 40).padEnd(42)) +
                             chalk_1.default.gray(`${c.bot_id.padEnd(14)}`) +
@@ -289,17 +301,149 @@ function registerCommitmentsCommands(program) {
             await (0, database_1.closeConnection)();
         }
     });
+    // ── semo commitments claim ──────────────────────────────────────────────────
+    cmd
+        .command('claim <id>')
+        .description('세션이 commitment를 점유 (assigned_session 설정)')
+        .requiredOption('--session <key>', '세션 키')
+        .option('--owner <name>', '세션 소유자 (예: reus-local)')
+        .action(async (id, options) => {
+        const connected = await (0, database_1.isDbConnected)();
+        if (!connected) {
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
+            await (0, database_1.closeConnection)();
+            process.exit(1);
+        }
+        try {
+            const pool = (0, database_1.getPool)();
+            // 이미 다른 세션이 점유 중이면 실패
+            const result = await pool.query(`UPDATE semo.bot_commitments
+           SET assigned_session = $2,
+               session_owner = $3,
+               status = CASE WHEN status = 'pending' THEN 'active' ELSE status END,
+               last_heartbeat_at = NOW(),
+               updated_at = NOW()
+           WHERE id = $1
+             AND status IN ('pending', 'active')
+             AND (assigned_session IS NULL OR assigned_session = $2)
+           RETURNING id, title, status`, [id, options.session, options.owner ?? null]);
+            if (result.rowCount === 0) {
+                console.error(chalk_1.default.yellow('⚠ commitment 없거나 이미 다른 세션이 점유 중'));
+                process.exit(1);
+            }
+            else {
+                const row = result.rows[0];
+                console.log(chalk_1.default.green(`✔ claimed: ${row.id} — ${row.title} (${row.status})`));
+                console.log(JSON.stringify({ id: row.id, status: row.status, session: options.session }));
+            }
+        }
+        catch (err) {
+            console.error(chalk_1.default.red(`❌ claim 실패: ${err}`));
+            process.exit(1);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+    // ── semo commitments release ──────────────────────────────────────────────
+    cmd
+        .command('release')
+        .description('세션 종료 시 미완료 commitment 해제 (assigned_session 초기화)')
+        .requiredOption('--session <key>', '세션 키')
+        .action(async (options) => {
+        const connected = await (0, database_1.isDbConnected)();
+        if (!connected) {
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
+            await (0, database_1.closeConnection)();
+            process.exit(1);
+        }
+        try {
+            const pool = (0, database_1.getPool)();
+            const result = await pool.query(`UPDATE semo.bot_commitments
+           SET assigned_session = NULL,
+               session_owner = NULL,
+               status = CASE WHEN status = 'active' THEN 'pending' ELSE status END,
+               updated_at = NOW()
+           WHERE assigned_session = $1
+             AND status IN ('pending', 'active')
+           RETURNING id, title`, [options.session]);
+            if (result.rowCount === 0) {
+                console.log(chalk_1.default.gray('ℹ 해제할 commitment 없음'));
+            }
+            else {
+                for (const row of result.rows) {
+                    console.log(chalk_1.default.green(`✔ released: ${row.id} — ${row.title}`));
+                }
+            }
+        }
+        catch (err) {
+            console.error(chalk_1.default.red(`❌ release 실패: ${err}`));
+            process.exit(1);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+    // ── semo commitments stale ────────────────────────────────────────────────
+    cmd
+        .command('stale')
+        .description('stale commitment 감지 (장기간 상태 변경 없음)')
+        .option('--threshold <hours>', 'stale 판단 기준 시간', '24')
+        .option('--format <type>', '출력 형식 (table|json)', 'table')
+        .action(async (options) => {
+        const connected = await (0, database_1.isDbConnected)();
+        if (!connected) {
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
+            await (0, database_1.closeConnection)();
+            process.exit(1);
+        }
+        try {
+            const pool = (0, database_1.getPool)();
+            const hours = parseInt(options.threshold);
+            const result = await pool.query(`SELECT id, bot_id, status, title, assigned_session, session_owner,
+                  updated_at::text, EXTRACT(EPOCH FROM NOW() - updated_at)/3600 AS hours_stale
+           FROM semo.bot_commitments
+           WHERE status IN ('pending', 'active')
+             AND updated_at < NOW() - INTERVAL '1 hour' * $1
+           ORDER BY updated_at ASC`, [hours]);
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result.rows, null, 2));
+            }
+            else {
+                if (result.rows.length === 0) {
+                    console.log(chalk_1.default.green(`✅ stale commitment 없음 (기준: ${hours}시간)`));
+                }
+                else {
+                    console.log(chalk_1.default.yellow.bold(`\n⏰ Stale Commitments (${hours}h+)\n`));
+                    for (const c of result.rows) {
+                        console.log(`  ${chalk_1.default.red(Math.round(c.hours_stale) + 'h')} ` +
+                            chalk_1.default.white(c.title.slice(0, 40).padEnd(42)) +
+                            chalk_1.default.gray(c.bot_id.padEnd(14)) +
+                            chalk_1.default.gray(c.session_owner ?? 'no-owner'));
+                    }
+                    console.log();
+                }
+            }
+        }
+        catch (err) {
+            console.error(chalk_1.default.red(`❌ stale 실패: ${err}`));
+            process.exit(1);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
     // ── semo commitments watch ─────────────────────────────────────────────────
     cmd
-        .command("watch")
-        .description("워치독 — 활성 약속의 health 상태 조회")
-        .option("--format <type>", "출력 형식 (table|json)", "table")
-        .option("--bot-id <id>", "특정 봇만 필터")
-        .option("--exclude-bot <id>", "특정 봇 제외")
+        .command('watch')
+        .description('워치독 — 활성 약속의 health 상태 조회')
+        .option('--format <type>', '출력 형식 (table|json)', 'table')
+        .option('--bot-id <id>', '특정 봇만 필터')
+        .option('--exclude-bot <id>', '특정 봇 제외')
         .action(async (options) => {
         const connected = await (0, database_1.isDbConnected)();
         if (!connected) {
-            console.error(chalk_1.default.red("❌ DB 연결 실패"));
+            console.error(chalk_1.default.red('❌ DB 연결 실패'));
             await (0, database_1.closeConnection)();
             process.exit(1);
         }
@@ -316,9 +460,7 @@ function registerCommitmentsCommands(program) {
                 conditions.push(`bot_id != $${paramIdx++}`);
                 params.push(options.excludeBot);
             }
-            const whereClause = conditions.length > 0
-                ? `WHERE ${conditions.join(" AND ")}`
-                : "";
+            const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
             const result = await pool.query(`SELECT id, bot_id, status, title, description, source_type, source_ref,
                   deadline_at::text,
                   health, minutes_since_heartbeat, minutes_overdue,
@@ -332,37 +474,39 @@ function registerCommitmentsCommands(program) {
                ELSE 2
              END,
              deadline_at ASC NULLS LAST`, params);
-            if (options.format === "json") {
+            if (options.format === 'json') {
                 const summary = {
                     total: result.rows.length,
-                    overdue: result.rows.filter((r) => r.health === "overdue").length,
-                    stale: result.rows.filter((r) => r.health === "stale").length,
-                    on_track: result.rows.filter((r) => r.health === "on-track").length,
+                    overdue: result.rows.filter((r) => r.health === 'overdue').length,
+                    stale: result.rows.filter((r) => r.health === 'stale').length,
+                    on_track: result.rows.filter((r) => r.health === 'on-track').length,
                     commitments: result.rows,
                 };
                 console.log(JSON.stringify(summary, null, 2));
             }
             else {
-                console.log(chalk_1.default.cyan.bold("\n🔍 Commitment Watchdog\n"));
+                console.log(chalk_1.default.cyan.bold('\n🔍 Commitment Watchdog\n'));
                 if (result.rows.length === 0) {
-                    console.log(chalk_1.default.green("  ✅ 활성 약속 없음 — all clear"));
+                    console.log(chalk_1.default.green('  ✅ 활성 약속 없음 — all clear'));
                 }
                 else {
                     for (const c of result.rows) {
-                        const healthColor = c.health === "overdue" ? chalk_1.default.red.bold :
-                            c.health === "stale" ? chalk_1.default.yellow :
-                                chalk_1.default.green;
+                        const healthColor = c.health === 'overdue'
+                            ? chalk_1.default.red.bold
+                            : c.health === 'stale'
+                                ? chalk_1.default.yellow
+                                : chalk_1.default.green;
                         const overdue = c.minutes_overdue != null && c.minutes_overdue > 0
                             ? ` (${Math.round(c.minutes_overdue)}분 초과)`
-                            : "";
+                            : '';
                         console.log(`  ${healthColor(c.health.padEnd(10))} ` +
                             chalk_1.default.white(c.title.slice(0, 35).padEnd(37)) +
                             chalk_1.default.gray(c.bot_id.padEnd(14)) +
                             chalk_1.default.gray(`hb: ${Math.round(c.minutes_since_heartbeat)}분 전`) +
                             chalk_1.default.red(overdue));
                     }
-                    const overdue = result.rows.filter((r) => r.health === "overdue").length;
-                    const stale = result.rows.filter((r) => r.health === "stale").length;
+                    const overdue = result.rows.filter((r) => r.health === 'overdue').length;
+                    const stale = result.rows.filter((r) => r.health === 'stale').length;
                     console.log();
                     if (overdue > 0)
                         console.log(chalk_1.default.red.bold(`  ⚠ ${overdue}건 overdue`));

package/dist/commands/context-preserve.d.ts

@@ -0,0 +1,8 @@
+/**
+ * semo context-preserve — PreCompact 훅에서 호출
+ *
+ * 컨텍스트 압축 전에 세션의 미기록 의사결정/로그를 KB에 flush.
+ * stdin으로 { session_id, transcript_path } 수신.
+ */
+import { Command } from 'commander';
+export declare function registerContextPreserveCommands(program: Command): void;

package/dist/commands/context-preserve.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * semo context-preserve — PreCompact 훅에서 호출
+ *
+ * 컨텍스트 압축 전에 세션의 미기록 의사결정/로그를 KB에 flush.
+ * stdin으로 { session_id, transcript_path } 수신.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerContextPreserveCommands = registerContextPreserveCommands;
+const fs = __importStar(require("fs"));
+const database_1 = require("../database");
+const kb_1 = require("../kb");
+// 의사결정 패턴 감지
+const DECISION_PATTERNS = [
+    /결정[:\s].*(?:하기로|했다|합의|확정)/,
+    /합의[:\s]/,
+    /방침[:\s]/,
+    /도입하기로/,
+    /폐기하기로/,
+    /변경하기로/,
+];
+function registerContextPreserveCommands(program) {
+    program
+        .command('context-preserve')
+        .description('PreCompact 훅 — 압축 전 KB에 결정/로그 flush')
+        .action(async () => {
+        let transcriptPath = '';
+        try {
+            const input = await readStdin();
+            if (input) {
+                const parsed = JSON.parse(input);
+                transcriptPath = parsed.transcript_path || '';
+            }
+        }
+        catch {
+            // stdin 없음
+        }
+        const connected = await (0, database_1.isDbConnected)();
+        if (!connected) {
+            process.exit(0);
+        }
+        try {
+            if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+                process.stderr.write('[context-preserve] transcript_path 없음, skip\n');
+                process.exit(0);
+            }
+            const transcript = fs.readFileSync(transcriptPath, 'utf8');
+            // 의사결정 패턴 감지
+            const decisions = [];
+            const lines = transcript.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (DECISION_PATTERNS.some((p) => p.test(line))) {
+                    // 전후 2줄 컨텍스트 포함
+                    const context = lines.slice(Math.max(0, i - 2), Math.min(lines.length, i + 3));
+                    decisions.push(context.join('\n'));
+                }
+            }
+            if (decisions.length === 0) {
+                process.stderr.write('[context-preserve] 기록할 의사결정 없음\n');
+                process.exit(0);
+            }
+            // KB에 세션 로그로 기록
+            const today = new Date().toISOString().slice(0, 10);
+            const content = `# 세션 의사결정 로그 (${today})\n\n${decisions.map((d, i) => `## ${i + 1}\n${d}`).join('\n\n')}`;
+            const pool = (0, database_1.getPool)();
+            await (0, kb_1.kbPush)(pool, [
+                {
+                    domain: 'semicolon',
+                    key: 'session-log',
+                    sub_key: `${today}-${Date.now()}`,
+                    content,
+                    metadata: { source: 'context-preserve', decision_count: decisions.length },
+                },
+            ]);
+            process.stderr.write(`[context-preserve] ${decisions.length}건 의사결정 KB에 기록\n`);
+        }
+        catch (err) {
+            process.stderr.write(`[context-preserve] error: ${err}\n`);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (data += chunk));
+        process.stdin.on('end', () => resolve(data.trim()));
+        setTimeout(() => resolve(data.trim()), 500);
+    });
+}

package/dist/commands/incubator.js

@@ -103,26 +103,18 @@ function writeClaudeMd(sessionDir, serviceId, serviceName, channel) {
 유저 메시지를 받으면 아래 우선순위로 봇 Agent를 선택:
 
 1. **명시적 봇 지정**: "디자인팀에게 물어봐" → Agent(designclaw)
-2. **현재 Phase 기반**: Dashboard API에서 current_phase 조회 → PHASE_ASSIGNEES 매핑
+2. **현재 Phase 기반**: Dashboard API에서 current_phase 조회 → Phase별 담당 봇 매핑
 3. **키워드 분기**: 인프라/배포 → infraclaw, 리뷰/PR → reviewclaw, 마케팅/SEO → growthclaw
 4. **폴백**: Agent(semiclaw) — PM/오케스트레이터
 
-### Phase → 봇 매핑
-
-| Phase | 봇 | 트랙 |
-|-------|-----|------|
-| 0 | semiclaw | A |
-| 1-3 | planclaw | A |
-| 4 | designclaw | A |
-| 5-6 | planclaw | A |
-| 7-8 | workclaw | A |
-| 9 | planclaw | A |
-| Infra 0-2 | infraclaw | B |
+Phase → 봇 매핑은 Dashboard API \`GET /api/projects/{service_id}\`의 current_phase에 따름.
+봇 프로필은 KB에서 동적 로드됨 (\`semo kb get {botId} slack-config\`).
 
 ### 응답 포맷
 
-모든 응답 앞에 \`[봇이름]\` 접두사를 붙여 어떤 전문 봇이 응답했는지 표시.
-예: \`[PlanClaw] 비즈니스 모델 분석 결과입니다...\`
+reply() 호출 시 반드시 \`bot_id\` 파라미터를 전달하여 봇 정체성을 표시.
+예: \`reply(text="분석 결과입니다...", bot_id="planclaw", ...)\`
+응답 텍스트에 [봇이름] 접두사를 붙이지 않는다 — bot_id가 Slack 표시를 자동 처리.
 
 ## KB 도메인
 

package/dist/global-cache.js

@@ -161,9 +161,8 @@ async function syncGlobalCache(claudeDir) {
             cmdCount++;
         }
     }
-    // 3. 에이전트 설치 (전체 교체, 대소문자 중복 제거)
+    // 3. 에이전트 설치 (머지 모드 — 로컬 YAML frontmatter 보존)
     const agentsDir = path.join(dir, 'agents');
-    removeRecursive(agentsDir);
     fs.mkdirSync(agentsDir, { recursive: true });
     const seenAgentNames = new Set();
     const dedupedAgents = [];
@@ -174,30 +173,62 @@ async function syncGlobalCache(claudeDir) {
             dedupedAgents.push(agent);
         }
     }
+    // 기존 로컬 파일의 frontmatter 캐싱 (덮어쓰기 전)
+    const existingFrontmatters = new Map();
+    for (const folder of fs.readdirSync(agentsDir).filter((f) => !f.startsWith('.'))) {
+        const filePath = path.join(agentsDir, folder, `${folder}.md`);
+        if (fs.existsSync(filePath)) {
+            const existing = fs.readFileSync(filePath, 'utf8');
+            const fmMatch = existing.match(/^---\n([\s\S]*?)\n---\n/);
+            if (fmMatch) {
+                existingFrontmatters.set(folder.toLowerCase(), fmMatch[1]);
+            }
+        }
+    }
+    // DB에 없는 에이전트 폴더 정리 (orphan 제거)
+    const dbAgentNames = new Set(dedupedAgents.map((a) => a.name.toLowerCase()));
+    for (const folder of fs.readdirSync(agentsDir).filter((f) => !f.startsWith('.'))) {
+        const folderPath = path.join(agentsDir, folder);
+        if (!dbAgentNames.has(folder.toLowerCase()) && fs.statSync(folderPath).isDirectory()) {
+            removeRecursive(folderPath);
+        }
+    }
     for (const agent of dedupedAgents) {
         const agentFolder = path.join(agentsDir, agent.name);
         fs.mkdirSync(agentFolder, { recursive: true });
-        let content = agent.content;
+        // DB content에서 frontmatter 제거 (body만 추출)
+        let dbBody = agent.content;
+        const dbFmMatch = agent.content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+        if (dbFmMatch) {
+            dbBody = dbFmMatch[1].trim();
+        }
         // 위임 매트릭스 주입
         const agentDelegations = delegations.filter((d) => d.from_bot_id === agent.name);
         if (agentDelegations.length > 0) {
             const delegationLines = agentDelegations
                 .map((d) => `- → ${d.to_bot_id}: ${d.domains.join(', ')} (via ${d.method})`)
                 .join('\n');
-            content += `\n\n## 위임 매트릭스\n${delegationLines}\n`;
+            dbBody += `\n\n## 위임 매트릭스\n${delegationLines}\n`;
         }
-        // metadata에 model/description이 있으면 YAML frontmatter 주입
-        if (agent.metadata && (agent.metadata.model || agent.metadata.description)) {
-            const hasFrontmatter = content.trimStart().startsWith('---');
-            if (!hasFrontmatter) {
-                const fm = ['---'];
-                if (agent.metadata.description)
-                    fm.push(`description: "${agent.metadata.description}"`);
-                if (agent.metadata.model)
-                    fm.push(`model: "${agent.metadata.model}"`);
-                fm.push('---', '');
-                content = fm.join('\n') + content;
-            }
+        // 로컬 frontmatter 보존 (있으면) → DB body와 합침
+        const localFm = existingFrontmatters.get(agent.name.toLowerCase());
+        let content;
+        if (localFm) {
+            // 로컬 frontmatter 우선 보존 + DB body 업데이트
+            content = `---\n${localFm}\n---\n${dbBody}`;
+        }
+        else if (agent.metadata && (agent.metadata.model || agent.metadata.description)) {
+            // 로컬 frontmatter 없으면 metadata에서 생성
+            const fm = ['---'];
+            if (agent.metadata.description)
+                fm.push(`description: "${agent.metadata.description}"`);
+            if (agent.metadata.model)
+                fm.push(`model: "${agent.metadata.model}"`);
+            fm.push('---', '');
+            content = fm.join('\n') + dbBody;
+        }
+        else {
+            content = dbBody;
         }
         fs.writeFileSync(path.join(agentFolder, `${agent.name}.md`), content);
     }

package/dist/index.js

@@ -66,6 +66,8 @@ const db_1 = require("./commands/db");
 const memory_1 = require("./commands/memory");
 const test_1 = require("./commands/test");
 const commitments_1 = require("./commands/commitments");
+const agent_flush_1 = require("./commands/agent-flush");
+const context_preserve_1 = require("./commands/context-preserve");
 const service_1 = require("./commands/service");
 const harness_1 = require("./commands/harness");
 const incubator_1 = require("./commands/incubator");
@@ -890,6 +892,18 @@ async function setupHooks(isUpdate = false) {
                 ],
             },
         ],
+        PreCompact: [
+            {
+                matcher: 'auto',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: '. ~/.claude/semo/.env 2>/dev/null; semo context-preserve 2>/dev/null || true',
+                        timeout: 10000,
+                    },
+                ],
+            },
+        ],
     };
     // 기존 설정 로드 또는 새로 생성
     let existingSettings = {};
@@ -1690,6 +1704,7 @@ kbCmd
     .requiredOption('--content <text>', '항목 본문')
     .option('--metadata <json>', '추가 메타데이터 (JSON 문자열)')
     .option('--created-by <name>', '작성자 식별자', 'semo-cli')
+    .option('--expect-version <n>', 'Optimistic locking — 기대 version (불일치 시 실패)')
     .action(async (domain, key, subKey, options) => {
     const spinner = (0, ora_1.default)('KB upsert 중...').start();
     try {
@@ -1702,6 +1717,7 @@ kbCmd
             content: options.content,
             metadata,
             created_by: options.createdBy,
+            expect_version: options.expectVersion ? parseInt(options.expectVersion) : undefined,
         });
         if (result.success) {
             spinner.succeed(`KB upsert 완료: ${domain}/${key}${subKey ? '/' + subKey : ''}`);
@@ -2410,6 +2426,8 @@ ontoCmd
 (0, service_1.registerServiceCommands)(program);
 (0, harness_1.registerHarnessCommands)(program);
 (0, incubator_1.registerIncubatorCommands)(program);
+(0, agent_flush_1.registerAgentFlushCommands)(program);
+(0, context_preserve_1.registerContextPreserveCommands)(program);
 // === semo skills — DB 시딩 ===
 /**
  * SKILL.md frontmatter 파싱 (YAML 파서 없이 regex 기반)

package/dist/kb.d.ts

@@ -154,6 +154,7 @@ export declare function kbUpsert(pool: Pool, entry: {
     content: string;
     metadata?: Record<string, unknown>;
     created_by?: string;
+    expect_version?: number;
 }): Promise<{
     success: boolean;
     error?: string;

package/dist/kb.js

@@ -886,20 +886,44 @@ async function kbUpsert(pool, entry) {
     const embeddingStr = `[${embedding.join(',')}]`;
     const writeClient = await pool.connect();
     try {
-        await writeClient.query(`INSERT INTO semo.knowledge_base (domain, key, sub_key, content, metadata, created_by, embedding)
-       VALUES ($1, $2, $3, $4, $5, $6, $7::vector)
-       ON CONFLICT (domain, key, sub_key) DO UPDATE SET
-         content = EXCLUDED.content,
-         metadata = EXCLUDED.metadata,
-         embedding = EXCLUDED.embedding`, [
-            entry.domain,
-            key,
-            subKey,
-            entry.content,
-            JSON.stringify(entry.metadata || {}),
-            entry.created_by || 'semo-cli',
-            embeddingStr,
-        ]);
+        if (entry.expect_version !== undefined) {
+            // Optimistic locking: version 불일치 시 실패
+            // version/updated_at는 트리거(trg_kb_updated_at)가 자동 처리하므로 명시하지 않음
+            const result = await writeClient.query(`UPDATE semo.knowledge_base
+         SET content = $1, metadata = $2, embedding = $3::vector
+         WHERE domain = $4 AND key = $5 AND sub_key = $6 AND version = $7
+         RETURNING version`, [
+                entry.content,
+                JSON.stringify(entry.metadata || {}),
+                embeddingStr,
+                entry.domain,
+                key,
+                subKey,
+                entry.expect_version,
+            ]);
+            if (result.rowCount === 0) {
+                return {
+                    success: false,
+                    error: `version 충돌: 다른 세션이 이미 수정했습니다 (expected version ${entry.expect_version}). 다시 조회 후 재시도하세요.`,
+                };
+            }
+        }
+        else {
+            await writeClient.query(`INSERT INTO semo.knowledge_base (domain, key, sub_key, content, metadata, created_by, embedding)
+         VALUES ($1, $2, $3, $4, $5, $6, $7::vector)
+         ON CONFLICT (domain, key, sub_key) DO UPDATE SET
+           content = EXCLUDED.content,
+           metadata = EXCLUDED.metadata,
+           embedding = EXCLUDED.embedding`, [
+                entry.domain,
+                key,
+                subKey,
+                entry.content,
+                JSON.stringify(entry.metadata || {}),
+                entry.created_by || 'semo-cli',
+                embeddingStr,
+            ]);
+        }
         // KB→DB 동기화: Dashboard API에 위임 (파서 단일화)
         if ((key === 'kpi' || key === 'action-item') && subKey) {
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-semicolon/semo-cli",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "description": "SEMO CLI - AI Agent Orchestration Framework Installer",
   "main": "dist/index.js",
   "bin": {