@pic-ai/pic-agent-call 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vance-PIC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/pic-agent-call

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('./server.mjs');

package/bin/server.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { resolveMemoryPaths, initDatabase } from '../src/db.mjs';
+import * as memory from '../src/memory.mjs';
+import * as channel from '../src/channel.mjs';
+import * as tasks from '../src/tasks.mjs';
+import {
+    resolveSessionId,
+    getRegistration,
+    findAgentIdConflict,
+    registerAgent,
+    getAgentStatus,
+} from '../src/status.mjs';
+
+const { dbPath, jsonPath } = resolveMemoryPaths();
+let db;
+try {
+    db = initDatabase(dbPath, jsonPath);
+    process.stderr.write(`[pic-agent-call] DB: ${dbPath}\n`);
+} catch (err) {
+    process.stderr.write(`[pic-agent-call] DB init failed: ${err.message}\n`);
+    process.exit(1);
+}
+
+const server = new McpServer({ name: 'pic-agent-call', version: '1.0.0' });
+
+function text(str) { return { content: [{ type: 'text', text: String(str) }] }; }
+function textJson(obj) { return text(JSON.stringify(obj, null, 2)); }
+function errResult(msg) { return { content: [{ type: 'text', text: msg }], isError: true }; }
+
+// ── Memory 客製化 ──────────────────────────────────────────────────────────────
+
+server.tool('add-observation',
+    '【客製化】向指定記憶實體寫入觀測紀錄。實體不存在時自動建立，並同步更新 JSON 快照。',
+    { entityName: z.string().min(1).max(100).describe('記憶實體名稱'),
+      observationText: z.string().min(1).max(2000).describe('觀測文字內容') },
+    async ({ entityName, observationText }) => {
+        await memory.addObservation(db, jsonPath, entityName.trim(), observationText.trim());
+        return text(`✅ 已成功將 Observations 同步至 Memory 實體：${entityName.trim()}`);
+    }
+);
+
+server.tool('query-entity',
+    '【客製化】查詢指定記憶實體的完整資訊，含屬性、關係及所有歷程觀測紀錄。',
+    { entityName: z.string().min(1).describe('要查詢的記憶實體名稱') },
+    async ({ entityName }) => {
+        const r = memory.queryEntity(db, entityName.trim());
+        if (!r) return errResult(`❌ 找不到實體：${entityName.trim()}`);
+        return textJson(r);
+    }
+);
+
+server.tool('stats',
+    '【客製化】取得 SQLite 資料庫統計資訊，包括 Entities、Relations、Observations 筆數與路徑。',
+    {},
+    async () => {
+        const s = memory.getStats(db, dbPath);
+        return text([
+            '====================================',
+            '🧠 SQLite Memory MCP 大腦統計資訊',
+            '====================================',
+            `- 知識實體 (Entities)    : ${s.entities}`,
+            `- 關係節點 (Relations)   : ${s.relations}`,
+            `- 觀察記錄 (Observations): ${s.observations}`,
+            `- 資料庫路徑             : ${s.dbPath}`,
+            '====================================',
+        ].join('\n'));
+    }
+);
+
+// ── Memory 官方相容 ────────────────────────────────────────────────────────────
+
+server.tool('create_entities',
+    '【官方相容】建立多個新的知識實體。同名實體已存在則忽略。',
+    { entities: z.array(z.object({ name: z.string(), entityType: z.string(), observations: z.array(z.string()).optional() })) },
+    async ({ entities }) => {
+        memory.createEntities(db, jsonPath, entities);
+        return text(`✅ 已成功建立 ${entities.length} 個實體。`);
+    }
+);
+
+server.tool('add_observations',
+    '【官方相容】向多個已存在的知識實體添加新的觀測記錄。實體不存在則失敗。',
+    { observations: z.array(z.object({ entityName: z.string(), contents: z.array(z.string()) })) },
+    async ({ observations }) => {
+        memory.addObservations(db, jsonPath, observations);
+        return text('✅ 已成功為指定的實體新增觀測值。');
+    }
+);
+
+server.tool('create_relations',
+    '【官方相容】在兩個實體之間建立單向關聯關係。實體不存在會自動建立臨時實體。',
+    { relations: z.array(z.object({ from: z.string(), to: z.string(), relationType: z.string() })) },
+    async ({ relations }) => {
+        memory.createRelations(db, jsonPath, relations);
+        return text(`✅ 已成功建立 ${relations.length} 個實體關聯。`);
+    }
+);
+
+server.tool('read_graph',
+    '【官方相容】讀取並匯出當前完整的知識圖譜（含所有實體、觀測紀錄及關係）。',
+    {},
+    async () => textJson(memory.readGraph(db))
+);
+
+server.tool('search_nodes',
+    '【官方相容】模糊搜尋知識圖譜。範圍涵蓋實體名稱、類型及觀測紀錄內容。',
+    { query: z.string().describe('要搜尋的關鍵字') },
+    async ({ query }) => textJson(memory.searchNodes(db, query))
+);
+
+// ── Task-Broker ────────────────────────────────────────────────────────────────
+
+server.tool('create_task',
+    '【task-broker】建立任務記錄。相同 feature+payload 的任務具備冪等保護，不會重複建立。',
+    { feature: z.string().min(1).max(100), assign_to: z.string().min(1).max(50),
+      payload: z.string().max(65536), type: z.enum(['task','final']).optional(),
+      relay_to: z.string().max(50).optional() },
+    async (args) => {
+        const r = tasks.createTask(db, args.feature, args.assign_to, args.payload, args.type, args.relay_to);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+server.tool('list_pending_tasks',
+    '【task-broker】列出待處理（pending）任務。自動釋放逾時（>30 分鐘）的 claimed 任務。',
+    { assign_to: z.string().optional() },
+    async (args) => textJson(tasks.listPendingTasks(db, args.assign_to))
+);
+
+server.tool('claim_task',
+    '【task-broker】原子操作領取任務，防搶單。BEGIN IMMEDIATE 交易確保排他性。',
+    { task_id: z.string(), agent_id: z.string().min(1).max(100) },
+    async (args) => {
+        const r = tasks.claimTask(db, args.task_id, args.agent_id);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+server.tool('complete_task',
+    '【task-broker】標記任務完成並寫回執行結果。任務須為 claimed 狀態。',
+    { task_id: z.string(), result: z.string().max(65536) },
+    async (args) => {
+        const r = tasks.completeTask(db, args.task_id, args.result);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+server.tool('fail_task',
+    '【task-broker】標記任務失敗並記錄原因。任務須為 claimed 狀態。',
+    { task_id: z.string(), fail_reason: z.string().max(1000) },
+    async (args) => {
+        const r = tasks.failTask(db, args.task_id, args.fail_reason);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+server.tool('get_task',
+    '【task-broker】查詢單一任務的完整詳情（不含 payload_hash）。',
+    { task_id: z.string() },
+    async (args) => {
+        const r = tasks.getTask(db, args.task_id);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+// ── Channel ───────────────────────────────────────────────────────────────────
+
+server.tool('channel_send',
+    '【channel】傳送訊息給指定 AI 視窗或 pool。',
+    { sender: z.string(), receiver: z.string(), message: z.string(),
+      priority: z.number().min(1).max(10).optional() },
+    async (args) => textJson(channel.sendMessage(db, args.sender, args.receiver, args.message, args.priority))
+);
+
+server.tool('channel_list_unread',
+    '【channel】列出指定接收者的未讀訊息。自動釋放逾時 IN_PROGRESS（>15 分鐘）。',
+    { receiver: z.string() },
+    async (args) => textJson(channel.listUnread(db, args.receiver))
+);
+
+server.tool('channel_claim',
+    '【channel】原子搶鎖：將 UNREAD 訊息標記為 IN_PROGRESS。',
+    { message_id: z.string(), agent_id: z.string() },
+    async (args) => {
+        const r = channel.claimMessage(db, args.message_id, args.agent_id);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+server.tool('channel_ack',
+    '【channel】確認完成：將 IN_PROGRESS 訊息標記為 READ。只有搶鎖者才能 ACK。',
+    { message_id: z.string(), agent_id: z.string() },
+    async (args) => {
+        const r = channel.ackMessage(db, args.message_id, args.agent_id);
+        return { content: [{ type: 'text', text: JSON.stringify(r) }], ...(r.success === false ? { isError: true } : {}) };
+    }
+);
+
+// ── Agent 身份管理 ────────────────────────────────────────────────────────────
+
+server.tool('register_agent',
+    '【agent】登記或更新當前 AI 視窗的身份（agent_id + role）。session_id 自動從環境變數讀取。若 agent_id 已被其他 session 占用，回傳 conflict 資訊供 AI 詢問 user。換角色時自動處理孤兒訊息並通知原始發送者。',
+    {
+        agent_id: z.string().min(1).max(50).describe('代理人識別碼，例如 CC-PG1'),
+        role: z.string().max(50).optional().describe('角色標籤，例如 PG、SA、DevOps'),
+    },
+    async ({ agent_id, role }) => {
+        const sessionId = resolveSessionId();
+
+        // 檢查 agent_id 是否被其他 session 占用
+        const conflict = findAgentIdConflict(db, agent_id, sessionId);
+        if (conflict) {
+            return textJson({
+                conflict: true,
+                occupied_by_session: conflict.session_id,
+                current_role: conflict.role,
+                message: `agent_id "${agent_id}" 已被另一個 session（${conflict.session_id}）占用。請選擇其他 agent_id，或確認該 session 是否已失效。`,
+            });
+        }
+
+        const result = registerAgent(db, sessionId, agent_id, role);
+        return textJson(result);
+    }
+);
+
+server.tool('agent_status',
+    '【agent】查詢當前 AI 視窗的身份與未讀訊息數量。session_id 自動讀取。',
+    {},
+    async () => {
+        const sessionId = resolveSessionId();
+        const reg = getRegistration(db, sessionId);
+
+        if (!reg) {
+            return textJson({
+                registered: false,
+                session_id: sessionId,
+                message: '尚未登記身份，請呼叫 register_agent',
+            });
+        }
+
+        const status = getAgentStatus(db, sessionId);
+        return textJson({
+            registered: true,
+            ...status,
+            session_id: sessionId,
+        });
+    }
+);
+
+// ── 啟動 ──────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write('[pic-agent-call] 已啟動，等待連線...\n');

package/bin/statusline.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// CC statusbar hook 用：查詢當前 session 的 agent 身份與未讀數，輸出一行，exit 0
+import { setup } from '../src/db.mjs';
+import { resolveSessionId, getRegistration, getAgentStatus } from '../src/status.mjs';
+
+let db;
+try {
+    ({ db } = setup());
+} catch (_) {
+    process.stdout.write('[DB ERR]\n');
+    process.exit(0);
+}
+
+const sessionId = resolveSessionId();
+const reg = getRegistration(db, sessionId);
+
+if (!reg) {
+    process.stdout.write('[未登記]\n');
+} else {
+    const status = getAgentStatus(db, sessionId);
+    process.stdout.write((status?.display ?? '[未知]') + '\n');
+}
+
+process.exit(0);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@pic-ai/pic-agent-call",
+  "version": "1.0.0",
+  "description": "AI multi-agent communication MCP server — Memory, Channel, Task-Broker",
+  "type": "module",
+  "bin": {
+    "pic-agent-call": "./bin/pic-agent-call"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/server.mjs",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --no-coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "jest": "^30.4.2"
+  }
+}

package/src/channel.mjs

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+
+export function sendMessage(db, sender, receiver, message, priority) {
+    const msgId = `msg-${randomUUID()}`;
+    const p = Number(priority) || 5;
+    db.prepare(
+        `INSERT INTO agent_collaboration_channel (message_id, sender, receiver, priority, message) VALUES (?, ?, ?, ?, ?)`
+    ).run(msgId, sender, receiver, p, message);
+    return { message_id: msgId, status: 'UNREAD' };
+}
+
+export function listUnread(db, receiver) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        db.prepare(
+            `UPDATE agent_collaboration_channel
+             SET status = 'UNREAD', lock_owner = NULL, lock_time = NULL, updated_at = datetime('now','localtime')
+             WHERE status = 'IN_PROGRESS' AND lock_time < datetime('now','localtime','-15 minutes')`
+        ).run();
+        db.exec('COMMIT');
+    } catch (_) {
+        try { db.exec('ROLLBACK'); } catch (__) {}
+    }
+
+    const pool = receiver.endsWith('?') ? receiver.slice(0, -1) : null;
+    let rows;
+    if (receiver === 'all') {
+        rows = db.prepare(`SELECT * FROM agent_collaboration_channel WHERE status='UNREAD' ORDER BY priority DESC, created_at ASC`).all();
+    } else if (pool) {
+        rows = db.prepare(`SELECT * FROM agent_collaboration_channel WHERE status='UNREAD' AND receiver LIKE ? ORDER BY priority DESC, created_at ASC`).all(`${pool}%`);
+    } else {
+        rows = db.prepare(`SELECT * FROM agent_collaboration_channel WHERE status='UNREAD' AND receiver=? ORDER BY priority DESC, created_at ASC`).all(receiver);
+    }
+    return { messages: rows, count: rows.length };
+}
+
+export function claimMessage(db, message_id, agent_id) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare(`SELECT status, lock_owner FROM agent_collaboration_channel WHERE message_id = ?`).get(message_id);
+        if (!row) { db.exec('ROLLBACK'); return { success: false, reason: 'message not found' }; }
+        if (row.status !== 'UNREAD') { db.exec('ROLLBACK'); return { success: false, reason: `already ${row.status} by ${row.lock_owner || 'unknown'}` }; }
+        db.prepare(
+            `UPDATE agent_collaboration_channel
+             SET status='IN_PROGRESS', lock_owner=?, lock_time=datetime('now','localtime'), updated_at=datetime('now','localtime')
+             WHERE message_id=? AND status='UNREAD' AND lock_owner IS NULL`
+        ).run(agent_id, message_id);
+        const updated = db.prepare(`SELECT lock_owner FROM agent_collaboration_channel WHERE message_id = ?`).get(message_id);
+        db.exec('COMMIT');
+        if (updated.lock_owner === agent_id) return { success: true, message_id };
+        return { success: false, reason: 'race: claimed by another agent' };
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        return { success: false, reason: err.message };
+    }
+}
+
+export function ackMessage(db, message_id, agent_id) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare(`SELECT status, lock_owner FROM agent_collaboration_channel WHERE message_id = ?`).get(message_id);
+        if (!row) { db.exec('ROLLBACK'); return { success: false, reason: 'message not found' }; }
+        if (row.status !== 'IN_PROGRESS' || row.lock_owner !== agent_id) {
+            db.exec('ROLLBACK');
+            return { success: false, reason: `not owned: status=${row.status} owner=${row.lock_owner}` };
+        }
+        db.prepare(`UPDATE agent_collaboration_channel SET status='READ', updated_at=datetime('now','localtime') WHERE message_id=?`).run(message_id);
+        db.exec('COMMIT');
+        return { success: true, message_id };
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        return { success: false, reason: err.message };
+    }
+}

package/src/db.mjs

@@ -0,0 +1,241 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { DatabaseSync } from 'node:sqlite';
+
+export const IDENTITY = `PID:${process.pid} | USER:${process.env.USERNAME || process.env.USER || 'unknown'}`;
+
+const MAX_RETRIES = 20;
+const RETRY_BASE_MS = 5;
+
+export function resolveMemoryPaths() {
+    if (process.env.MEMORY_DB_PATH) {
+        const dbPath = process.env.MEMORY_DB_PATH;
+        return { dbPath, jsonPath: path.join(path.dirname(dbPath), 'memory-graph.json') };
+    }
+
+    const settingsPath = path.join(process.cwd(), 'settings.local.json');
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            if (settings.memoryDbPath) {
+                const dbPath = settings.memoryDbPath;
+                return { dbPath, jsonPath: path.join(path.dirname(dbPath), 'memory-graph.json') };
+            }
+        } catch (_) {}
+    }
+
+    const projectMemoryDir = path.join(process.cwd(), '.memory');
+    try {
+        if (!fs.existsSync(projectMemoryDir)) fs.mkdirSync(projectMemoryDir, { recursive: true });
+        fs.accessSync(projectMemoryDir, fs.constants.W_OK);
+        return {
+            dbPath: path.join(projectMemoryDir, 'memory-graph.db'),
+            jsonPath: path.join(projectMemoryDir, 'memory-graph.json'),
+        };
+    } catch (_) {}
+
+    const homeMemoryDir = path.join(os.homedir(), '.memory');
+    if (!fs.existsSync(homeMemoryDir)) fs.mkdirSync(homeMemoryDir, { recursive: true });
+    return {
+        dbPath: path.join(homeMemoryDir, 'memory-graph.db'),
+        jsonPath: path.join(homeMemoryDir, 'memory-graph.json'),
+    };
+}
+
+export function initDatabase(dbPath, jsonPath) {
+    const db = new DatabaseSync(dbPath);
+
+    db.exec('PRAGMA busy_timeout = 30000');
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA foreign_keys = ON');
+
+    db.exec(`CREATE TABLE IF NOT EXISTS entities (
+        name TEXT PRIMARY KEY,
+        entityType TEXT NOT NULL,
+        description TEXT,
+        version INTEGER NOT NULL DEFAULT 1,
+        created_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+        last_written_by TEXT NOT NULL
+    )`);
+
+    db.exec(`CREATE TABLE IF NOT EXISTS relations (
+        from_entity TEXT NOT NULL,
+        to_entity TEXT NOT NULL,
+        relationType TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+        last_written_by TEXT NOT NULL,
+        PRIMARY KEY (from_entity, to_entity, relationType),
+        FOREIGN KEY (from_entity) REFERENCES entities(name) ON DELETE CASCADE,
+        FOREIGN KEY (to_entity) REFERENCES entities(name) ON DELETE CASCADE
+    )`);
+
+    db.exec(`CREATE TABLE IF NOT EXISTS observations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        entity_name TEXT NOT NULL,
+        observation TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+        last_written_by TEXT NOT NULL,
+        FOREIGN KEY (entity_name) REFERENCES entities(name) ON DELETE CASCADE
+    )`);
+
+    db.exec(`CREATE TABLE IF NOT EXISTS tasks (
+        task_id      TEXT PRIMARY KEY,
+        feature      TEXT NOT NULL,
+        assign_to    TEXT NOT NULL,
+        payload      TEXT NOT NULL,
+        type         TEXT NOT NULL DEFAULT 'task' CHECK(type IN ('task','final')),
+        status       TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','claimed','completed','failed')),
+        claimed_by   TEXT,
+        claimed_at   TEXT,
+        completed_at TEXT,
+        result       TEXT,
+        fail_reason  TEXT,
+        relay_to     TEXT,
+        payload_hash TEXT NOT NULL,
+        created_at   TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+        updated_at   TEXT NOT NULL DEFAULT (datetime('now', 'localtime'))
+    )`);
+    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_payload_hash ON tasks(payload_hash)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_status_assign ON tasks(status, assign_to)`);
+
+    db.exec(`CREATE TABLE IF NOT EXISTS agents (
+        agent_id          TEXT PRIMARY KEY,
+        last_seen         TEXT,
+        status            TEXT NOT NULL DEFAULT 'offline' CHECK(status IN ('active','offline')),
+        agent_timeout_sec INTEGER NOT NULL DEFAULT 120,
+        poll_interval_sec INTEGER NOT NULL DEFAULT 30,
+        term_key          TEXT,
+        created_at        TEXT NOT NULL DEFAULT (datetime('now','localtime')),
+        updated_at        TEXT NOT NULL DEFAULT (datetime('now','localtime'))
+    )`);
+
+    db.exec(`CREATE TABLE IF NOT EXISTS agent_collaboration_channel (
+        message_id TEXT PRIMARY KEY,
+        sender     TEXT NOT NULL,
+        receiver   TEXT NOT NULL,
+        priority   INTEGER DEFAULT 5,
+        status     TEXT DEFAULT 'UNREAD',
+        lock_owner TEXT,
+        lock_time  TEXT,
+        message    TEXT NOT NULL,
+        created_at TEXT DEFAULT (datetime('now','localtime')),
+        updated_at TEXT DEFAULT (datetime('now','localtime'))
+    )`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_acc_receiver_status ON agent_collaboration_channel(receiver, status)`);
+
+    // 向下相容遷移
+    for (const sql of [
+        `ALTER TABLE tasks ADD COLUMN type TEXT NOT NULL DEFAULT 'task' CHECK(type IN ('task','final'))`,
+        `ALTER TABLE tasks ADD COLUMN relay_to TEXT`,
+        `ALTER TABLE agents ADD COLUMN term_key TEXT`,
+        `ALTER TABLE agents ADD COLUMN session_id TEXT`,
+        `ALTER TABLE agents ADD COLUMN role TEXT`,
+    ]) {
+        try { db.exec(sql); } catch (_) {}
+    }
+    db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_agents_session_id ON agents(session_id)`);
+
+    const row = db.prepare('SELECT COUNT(*) as count FROM entities').get();
+    if (row.count === 0 && fs.existsSync(jsonPath)) {
+        _migrateFromJson(db, jsonPath);
+    }
+
+    return db;
+}
+
+export function setup(options = {}) {
+    const paths = options.dbPath
+        ? { dbPath: options.dbPath, jsonPath: path.join(path.dirname(options.dbPath), 'memory-graph.json') }
+        : resolveMemoryPaths();
+    const db = initDatabase(paths.dbPath, paths.jsonPath);
+    return { db, dbPath: paths.dbPath, jsonPath: paths.jsonPath };
+}
+
+export function syncDbToJson(db, jsonPath) {
+    const rows = db.prepare(`
+        SELECT e.name, e.entityType, e.description, o.observation
+        FROM entities e
+        LEFT JOIN observations o ON e.name = o.entity_name
+        ORDER BY e.name, o.id ASC
+    `).all();
+
+    const map = {};
+    for (const row of rows) {
+        if (!map[row.name]) {
+            map[row.name] = { type: 'entity', name: row.name, entityType: row.entityType, observations: [] };
+        }
+        if (row.observation) map[row.name].observations.push(row.observation);
+    }
+
+    const jsonLines = Object.values(map).map(o => JSON.stringify(o)).join('\n') + '\n';
+    const tmpPath = `${jsonPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, jsonLines, 'utf8');
+    try {
+        fs.renameSync(tmpPath, jsonPath);
+    } catch (_) {
+        try { fs.unlinkSync(tmpPath); } catch (__) {}
+        fs.writeFileSync(jsonPath, jsonLines, 'utf8');
+    }
+}
+
+export async function withRetry(fn, maxRetries = MAX_RETRIES) {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return fn();
+        } catch (err) {
+            const busy = String(err.message || '').includes('SQLITE_BUSY') ||
+                         String(err.message || '').includes('database is locked') ||
+                         err.code === 'ERR_OPTIMISTIC_LOCK_FAILED';
+            if (busy && i < maxRetries - 1) {
+                const wait = Math.pow(2, i) * RETRY_BASE_MS + Math.random() * 10;
+                await new Promise(r => setTimeout(r, wait));
+                continue;
+            }
+            if (busy) {
+                const e = new Error('ERR_DATABASE_LOCKED');
+                e.code = 'ERR_DATABASE_LOCKED';
+                throw e;
+            }
+            throw err;
+        }
+    }
+}
+
+function _migrateFromJson(db, jsonPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(jsonPath, 'utf8');
+        if (raw.startsWith('')) raw = raw.slice(1);
+    } catch (_) { return; }
+
+    const lines = raw.split(/\r?\n/).filter(l => l.trim());
+    if (!lines.length) return;
+
+    const insertEntity = db.prepare(
+        `INSERT OR IGNORE INTO entities (name, entityType, description, created_at, updated_at, last_written_by)
+         VALUES (?, ?, ?, datetime('now','localtime'), datetime('now','localtime'), ?)`
+    );
+    const insertObs = db.prepare(
+        `INSERT INTO observations (entity_name, observation, created_at, last_written_by)
+         VALUES (?, ?, datetime('now','localtime'), ?)`
+    );
+
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const line of lines) {
+            let entity;
+            try { entity = JSON.parse(line); } catch (_) { continue; }
+            if (!entity.name || !entity.entityType) continue;
+            insertEntity.run(entity.name, entity.entityType, entity.description || null, IDENTITY);
+            for (const obs of (entity.observations ?? [])) {
+                insertObs.run(entity.name, obs, IDENTITY);
+            }
+        }
+        db.exec('COMMIT');
+    } catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+}

package/src/memory.mjs

@@ -0,0 +1,144 @@
+import { IDENTITY, syncDbToJson, withRetry } from './db.mjs';
+
+export async function addObservation(db, jsonPath, entityName, observationText) {
+    await withRetry(() => {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const existing = db.prepare('SELECT name FROM entities WHERE name = ?').get(entityName);
+            if (!existing) {
+                db.prepare(
+                    `INSERT INTO entities (name, entityType, created_at, updated_at, last_written_by)
+                     VALUES (?, 'unknown', datetime('now','localtime'), datetime('now','localtime'), ?)`
+                ).run(entityName, IDENTITY);
+            } else {
+                db.prepare(
+                    `UPDATE entities SET version = version + 1, updated_at = datetime('now','localtime'), last_written_by = ? WHERE name = ?`
+                ).run(IDENTITY, entityName);
+            }
+            db.prepare(
+                `INSERT INTO observations (entity_name, observation, created_at, last_written_by)
+                 VALUES (?, ?, datetime('now','localtime'), ?)`
+            ).run(entityName, observationText, IDENTITY);
+            db.exec('COMMIT');
+        } catch (err) {
+            try { db.exec('ROLLBACK'); } catch (_) {}
+            throw err;
+        }
+    });
+    await withRetry(() => syncDbToJson(db, jsonPath));
+}
+
+export function queryEntity(db, entityName) {
+    const entity = db.prepare('SELECT * FROM entities WHERE name = ?').get(entityName);
+    if (!entity) return null;
+    const observations = db.prepare('SELECT observation FROM observations WHERE entity_name = ? ORDER BY id ASC').all(entityName).map(r => r.observation);
+    const relations = db.prepare('SELECT to_entity, relationType FROM relations WHERE from_entity = ?').all(entityName);
+    return { ...entity, observations, relations };
+}
+
+export function getStats(db, dbPath) {
+    return {
+        entities:     db.prepare('SELECT COUNT(*) as c FROM entities').get().c,
+        relations:    db.prepare('SELECT COUNT(*) as c FROM relations').get().c,
+        observations: db.prepare('SELECT COUNT(*) as c FROM observations').get().c,
+        dbPath,
+    };
+}
+
+export function createEntities(db, jsonPath, entities) {
+    const insertEntity = db.prepare(`INSERT OR IGNORE INTO entities (name, entityType, last_written_by) VALUES (?, ?, ?)`);
+    const insertObs    = db.prepare(`INSERT INTO observations (entity_name, observation, last_written_by) VALUES (?, ?, ?)`);
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const e of entities) {
+            if (!e.name || !e.entityType) continue;
+            insertEntity.run(e.name, e.entityType, IDENTITY);
+            for (const obs of (e.observations ?? [])) insertObs.run(e.name, obs, IDENTITY);
+        }
+        db.exec('COMMIT');
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        throw err;
+    }
+    syncDbToJson(db, jsonPath);
+}
+
+export function addObservations(db, jsonPath, observations) {
+    const check  = db.prepare('SELECT name FROM entities WHERE name = ?');
+    const insert = db.prepare(`INSERT INTO observations (entity_name, observation, last_written_by) VALUES (?, ?, ?)`);
+    const update = db.prepare(`UPDATE entities SET version = version + 1, updated_at = datetime('now'), last_written_by = ? WHERE name = ?`);
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const item of observations) {
+            if (!check.get(item.entityName)) throw new Error(`找不到指定的實體：${item.entityName}`);
+            for (const obs of item.contents) insert.run(item.entityName, obs, IDENTITY);
+            update.run(IDENTITY, item.entityName);
+        }
+        db.exec('COMMIT');
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        throw err;
+    }
+    syncDbToJson(db, jsonPath);
+}
+
+export function createRelations(db, jsonPath, relations) {
+    const check        = db.prepare('SELECT name FROM entities WHERE name = ?');
+    const insertEntity = db.prepare(`INSERT OR IGNORE INTO entities (name, entityType, last_written_by) VALUES (?, 'unknown', ?)`);
+    const insertRel    = db.prepare(`INSERT OR IGNORE INTO relations (from_entity, to_entity, relationType, last_written_by) VALUES (?, ?, ?, ?)`);
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const r of relations) {
+            if (!r.from || !r.to || !r.relationType) continue;
+            if (!check.get(r.from)) insertEntity.run(r.from, IDENTITY);
+            if (!check.get(r.to))   insertEntity.run(r.to, IDENTITY);
+            insertRel.run(r.from, r.to, r.relationType, IDENTITY);
+        }
+        db.exec('COMMIT');
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        throw err;
+    }
+    syncDbToJson(db, jsonPath);
+}
+
+export function readGraph(db) {
+    const entities = db.prepare('SELECT name, entityType FROM entities').all();
+    const obsRows  = db.prepare('SELECT entity_name, observation FROM observations ORDER BY id ASC').all();
+    const relRows  = db.prepare('SELECT from_entity, to_entity, relationType FROM relations').all();
+
+    const obsMap = {};
+    for (const r of obsRows) {
+        if (!obsMap[r.entity_name]) obsMap[r.entity_name] = [];
+        obsMap[r.entity_name].push(r.observation);
+    }
+    return {
+        entities: entities.map(e => ({ name: e.name, entityType: e.entityType, observations: obsMap[e.name] ?? [] })),
+        relations: relRows.map(r => ({ from: r.from_entity, to: r.to_entity, relationType: r.relationType })),
+    };
+}
+
+export function searchNodes(db, query) {
+    const q = `%${query}%`;
+    const entityRows = db.prepare('SELECT name, entityType FROM entities WHERE name LIKE ? OR entityType LIKE ?').all(q, q);
+    const obsRows    = db.prepare('SELECT DISTINCT entity_name FROM observations WHERE observation LIKE ?').all(q);
+
+    const matched = new Set([...entityRows.map(r => r.name), ...obsRows.map(r => r.entity_name)]);
+    if (!matched.size) return { entities: [], relations: [] };
+
+    const ph    = Array(matched.size).fill('?').join(',');
+    const names = Array.from(matched);
+    const matchedEntities = db.prepare(`SELECT name, entityType FROM entities WHERE name IN (${ph})`).all(...names);
+    const matchedObs      = db.prepare(`SELECT entity_name, observation FROM observations WHERE entity_name IN (${ph}) ORDER BY id ASC`).all(...names);
+    const matchedRels     = db.prepare(`SELECT from_entity, to_entity, relationType FROM relations WHERE from_entity IN (${ph}) OR to_entity IN (${ph})`).all(...names, ...names);
+
+    const obsMap = {};
+    for (const r of matchedObs) {
+        if (!obsMap[r.entity_name]) obsMap[r.entity_name] = [];
+        obsMap[r.entity_name].push(r.observation);
+    }
+    return {
+        entities: matchedEntities.map(e => ({ name: e.name, entityType: e.entityType, observations: obsMap[e.name] ?? [] })),
+        relations: matchedRels.map(r => ({ from: r.from_entity, to: r.to_entity, relationType: r.relationType })),
+    };
+}

package/src/status.mjs

@@ -0,0 +1,160 @@
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+// 解析當前 session_id（MCP server 啟動後繼承 parent env）
+export function resolveSessionId() {
+    return process.env.CLAUDE_CODE_SESSION_ID      // CC
+        || process.env.ANTIGRAVITY_CONVERSATION_ID  // AGY
+        || process.env.AGENT_SESSION_ID             // 通用
+        || `${os.hostname()}-${process.pid}`;       // fallback
+}
+
+// 查詢 session 是否已有 registration
+// 回傳 { agent_id, role, session_id } | null
+export function getRegistration(db, sessionId) {
+    return db.prepare(
+        'SELECT agent_id, role, session_id FROM agents WHERE session_id = ?'
+    ).get(sessionId) || null;
+}
+
+// 查詢 agent_id 是否被其他 session 占用
+// 回傳 { agent_id, session_id, role } | null
+export function findAgentIdConflict(db, agentId, sessionId) {
+    return db.prepare(
+        'SELECT agent_id, session_id, role FROM agents WHERE agent_id = ? AND session_id != ?'
+    ).get(agentId, sessionId) || null;
+}
+
+// 處理換角色時的孤兒訊息：
+// 1. 找舊 agent_id 的所有 UNREAD 訊息
+// 2. 對每個 sender 發送 channel 通知
+// 3. 把孤兒訊息標記為 ORPHANED
+// 回傳 orphan_count
+export function handleOrphanedMessages(db, oldAgentId, newAgentId) {
+    const orphans = db.prepare(
+        `SELECT message_id, sender, message FROM agent_collaboration_channel
+         WHERE receiver = ? AND status = 'UNREAD'`
+    ).all(oldAgentId);
+
+    if (orphans.length === 0) return 0;
+
+    const insertNotify = db.prepare(
+        `INSERT INTO agent_collaboration_channel
+             (message_id, sender, receiver, priority, message, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, datetime('now','localtime'), datetime('now','localtime'))`
+    );
+
+    const markOrphaned = db.prepare(
+        `UPDATE agent_collaboration_channel
+         SET status = 'ORPHANED', updated_at = datetime('now','localtime')
+         WHERE message_id = ?`
+    );
+
+    // 蒐集 sender 集合，每個 sender 只通知一次
+    const notifiedSenders = new Set();
+
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const row of orphans) {
+            if (!notifiedSenders.has(row.sender)) {
+                notifiedSenders.add(row.sender);
+                const notifyMsgId = `msg-${randomUUID()}`;
+                const notifyText = JSON.stringify({
+                    type: 'ORPHAN_NOTICE',
+                    original_receiver: oldAgentId,
+                    new_agent_id: newAgentId,
+                    message: `[系統] ${oldAgentId} 已重新登記為 ${newAgentId}，您傳送給 ${oldAgentId} 的訊息已成為孤兒訊息（ORPHANED），請重新傳送給 ${newAgentId}。`,
+                });
+                insertNotify.run(notifyMsgId, 'SYSTEM', row.sender, 8, notifyText);
+            }
+            markOrphaned.run(row.message_id);
+        }
+        db.exec('COMMIT');
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        throw err;
+    }
+
+    return orphans.length;
+}
+
+// Upsert agent registration
+// 若 agent_id 衝突（不同 session），呼叫者自行決定是否繼續
+// 回傳 { success, agent_id, role, session_id, previous?, orphans_notified? }
+export function registerAgent(db, sessionId, agentId, role) {
+    const existing = getRegistration(db, sessionId);
+    const previousAgentId = existing?.agent_id || null;
+    const previousRole = existing?.role || null;
+
+    let orphansNotified = 0;
+
+    // 若 agent_id 有變，處理孤兒訊息
+    if (previousAgentId && previousAgentId !== agentId) {
+        orphansNotified = handleOrphanedMessages(db, previousAgentId, agentId);
+    }
+
+    const now = `datetime('now','localtime')`;
+
+    if (existing) {
+        // UPDATE existing session
+        db.prepare(
+            `UPDATE agents
+             SET agent_id = ?, role = ?, updated_at = datetime('now','localtime')
+             WHERE session_id = ?`
+        ).run(agentId, role || null, sessionId);
+    } else {
+        // INSERT new registration
+        // agents 表以 agent_id 為 PRIMARY KEY，但我們希望以 session_id 為主鍵做 upsert
+        // 先嘗試 INSERT，若 agent_id 已存在（同 agent_id 不同 session）則會被 conflict check 擋掉
+        // 此函式呼叫前已由 findAgentIdConflict 確認無衝突
+        db.prepare(
+            `INSERT INTO agents (agent_id, role, session_id, last_seen, status, updated_at)
+             VALUES (?, ?, ?, datetime('now','localtime'), 'active', datetime('now','localtime'))
+             ON CONFLICT(agent_id) DO UPDATE SET
+                 role = excluded.role,
+                 session_id = excluded.session_id,
+                 last_seen = excluded.last_seen,
+                 status = 'active',
+                 updated_at = excluded.updated_at`
+        ).run(agentId, role || null, sessionId);
+    }
+
+    const result = {
+        success: true,
+        agent_id: agentId,
+        role: role || null,
+        session_id: sessionId,
+    };
+
+    if (previousAgentId !== null) {
+        result.previous = { agent_id: previousAgentId, role: previousRole };
+    }
+
+    if (orphansNotified > 0) {
+        result.orphans_notified = orphansNotified;
+    }
+
+    return result;
+}
+
+// 查詢 agent 狀態（給 statusline 用）
+// 回傳 { agent_id, role, unread, display }
+// display 格式：[CC-PG1|PG] 📨3
+export function getAgentStatus(db, sessionId) {
+    const reg = getRegistration(db, sessionId);
+    if (!reg) return null;
+
+    const { agent_id, role } = reg;
+
+    const row = db.prepare(
+        `SELECT COUNT(*) as count FROM agent_collaboration_channel
+         WHERE receiver = ? AND status = 'UNREAD'`
+    ).get(agent_id);
+
+    const unread = row?.count || 0;
+    const roleLabel = role ? `|${role}` : '';
+    const unreadLabel = unread > 0 ? ` 📨${unread}` : '';
+    const display = `[${agent_id}${roleLabel}]${unreadLabel}`;
+
+    return { agent_id, role: role || null, unread, display };
+}

package/src/tasks.mjs

@@ -0,0 +1,130 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+const TIMEOUT_MINUTES = 30;
+
+function _now() {
+    const d = new Date();
+    const offset = d.getTimezoneOffset() * 60000;
+    return new Date(d - offset).toISOString().replace('T', ' ').slice(0, 19);
+}
+
+export function initAgentsTable(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS agents (
+        agent_id          TEXT PRIMARY KEY,
+        last_seen         TEXT,
+        status            TEXT NOT NULL DEFAULT 'offline' CHECK(status IN ('active','offline')),
+        agent_timeout_sec INTEGER NOT NULL DEFAULT 120,
+        poll_interval_sec INTEGER NOT NULL DEFAULT 30,
+        term_key          TEXT,
+        created_at        TEXT NOT NULL DEFAULT (datetime('now','localtime')),
+        updated_at        TEXT NOT NULL DEFAULT (datetime('now','localtime'))
+    )`);
+    try { db.exec(`ALTER TABLE agents ADD COLUMN term_key TEXT`); } catch (_) {}
+}
+
+export function createTask(db, feature, assign_to, payload, type, relay_to) {
+    if (!feature || typeof feature !== 'string' || !feature.trim() || feature.length > 100)
+        return { success: false, reason: 'validation_error' };
+    if (!assign_to || typeof assign_to !== 'string' || !assign_to.trim() || assign_to.length > 50)
+        return { success: false, reason: 'validation_error' };
+    if (!payload || typeof payload !== 'string' || !payload.trim())
+        return { success: false, reason: 'validation_error' };
+    if (Buffer.byteLength(payload, 'utf8') > 65536)
+        return { success: false, reason: 'payload_too_large' };
+
+    const validTypes = ['task', 'final'];
+    if (type !== undefined && type !== null && !validTypes.includes(type))
+        return { success: false, reason: 'validation_error' };
+    const resolvedType = (type && validTypes.includes(type)) ? type : 'task';
+
+    const resolvedRelayTo = (relay_to && typeof relay_to === 'string' && relay_to.trim())
+        ? relay_to.trim() : null;
+    if (resolvedRelayTo !== null && resolvedRelayTo.length > 50)
+        return { success: false, reason: 'validation_error' };
+
+    const hash = createHash('sha256').update(feature + '|' + payload).digest('hex');
+    const existing = db.prepare('SELECT task_id, status, type FROM tasks WHERE payload_hash = ?').get(hash);
+    if (existing) return { task_id: existing.task_id, status: existing.status, type: existing.type, idempotent: true };
+
+    const taskId = 'task-' + randomUUID();
+    db.prepare('INSERT INTO tasks (task_id, feature, assign_to, payload, type, relay_to, payload_hash) VALUES (?, ?, ?, ?, ?, ?, ?)')
+      .run(taskId, feature.trim(), assign_to.trim(), payload, resolvedType, resolvedRelayTo, hash);
+    return { task_id: taskId, status: 'pending', type: resolvedType, idempotent: false };
+}
+
+export function listPendingTasks(db, assign_to) {
+    const assignTo = (assign_to && typeof assign_to === 'string') ? assign_to.trim() : null;
+    db.prepare(
+        `UPDATE tasks SET status='pending', claimed_by=NULL, claimed_at=NULL, updated_at=datetime('now','localtime')
+         WHERE status='claimed' AND claimed_at < datetime('now','localtime',? || ' minutes')`
+    ).run(`-${TIMEOUT_MINUTES}`);
+
+    const rows = assignTo
+        ? db.prepare(`SELECT task_id, feature, assign_to, payload, type, relay_to, status, created_at FROM tasks WHERE status='pending' AND assign_to=? ORDER BY created_at ASC`).all(assignTo)
+        : db.prepare(`SELECT task_id, feature, assign_to, payload, type, relay_to, status, created_at FROM tasks WHERE status='pending' ORDER BY created_at ASC`).all();
+    return { tasks: rows, count: rows.length };
+}
+
+export function claimTask(db, task_id, agent_id) {
+    if (!task_id || !agent_id || typeof agent_id !== 'string' || !agent_id.trim() || agent_id.length > 100)
+        return { success: false, reason: 'validation_error' };
+
+    const now = _now();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare('SELECT status, claimed_by FROM tasks WHERE task_id = ?').get(task_id);
+        if (!row) { db.exec('ROLLBACK'); return { success: false, reason: 'not_found', current_status: null, claimed_by: null }; }
+        if (row.status !== 'pending') { db.exec('ROLLBACK'); return { success: false, reason: 'already_claimed', current_status: row.status, claimed_by: row.claimed_by }; }
+        const changes = db.prepare(
+            `UPDATE tasks SET status='claimed', claimed_by=?, claimed_at=?, updated_at=? WHERE task_id=? AND status='pending'`
+        ).run(agent_id.trim(), now, now, task_id).changes;
+        if (changes === 0) { db.exec('ROLLBACK'); return { success: false, reason: 'already_claimed', current_status: 'claimed', claimed_by: null }; }
+        db.exec('COMMIT');
+        return { success: true, task_id, claimed_by: agent_id.trim(), claimed_at: now };
+    } catch (err) {
+        try { db.exec('ROLLBACK'); } catch (_) {}
+        throw err;
+    }
+}
+
+export function completeTask(db, task_id, result) {
+    if (!task_id || result === undefined || result === null)
+        return { success: false, reason: 'validation_error' };
+    const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+    if (Buffer.byteLength(resultStr, 'utf8') > 65536)
+        return { success: false, reason: 'payload_too_large' };
+
+    const row = db.prepare('SELECT status FROM tasks WHERE task_id = ?').get(task_id);
+    if (!row) return { success: false, task_id, reason: 'not_found' };
+    if (row.status !== 'claimed') return { success: false, task_id, reason: 'invalid_status', current_status: row.status };
+
+    const now = _now();
+    db.prepare(`UPDATE tasks SET status='completed', result=?, completed_at=?, updated_at=? WHERE task_id=? AND status='claimed'`)
+      .run(resultStr, now, now, task_id);
+    return { success: true, task_id, status: 'completed', completed_at: now };
+}
+
+export function failTask(db, task_id, fail_reason) {
+    if (!task_id || !fail_reason || typeof fail_reason !== 'string' || !fail_reason.trim())
+        return { success: false, reason: 'validation_error' };
+    if (Buffer.byteLength(fail_reason, 'utf8') > 1000)
+        return { success: false, reason: 'payload_too_large' };
+
+    const row = db.prepare('SELECT status FROM tasks WHERE task_id = ?').get(task_id);
+    if (!row) return { success: false, task_id, reason: 'not_found' };
+    if (row.status !== 'claimed') return { success: false, task_id, reason: 'invalid_status', current_status: row.status };
+
+    const now = _now();
+    db.prepare(`UPDATE tasks SET status='failed', fail_reason=?, updated_at=? WHERE task_id=? AND status='claimed'`)
+      .run(fail_reason.trim(), now, task_id);
+    return { success: true, task_id, status: 'failed' };
+}
+
+export function getTask(db, task_id) {
+    if (!task_id) return { success: false, reason: 'validation_error' };
+    const row = db.prepare(
+        'SELECT task_id, feature, assign_to, payload, type, status, claimed_by, claimed_at, completed_at, result, fail_reason, created_at, updated_at FROM tasks WHERE task_id = ?'
+    ).get(task_id);
+    if (!row) return { success: false, reason: 'not_found' };
+    return row;
+}