lockage 0.0.0-stage → 0.9.1

package/dist/db/index.js

@@ -0,0 +1,238 @@
+import { DatabaseSync } from 'node:sqlite';
+import { readFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { hostname } from 'node:os';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Location of schema.sql.
+ * dev (tsx): read src/db/schema.sql directly.
+ * build (tsc): tsc does not copy .sql, so the schema is copied to dist/db/ at build time
+ * (handled by package.json's build script). Phase 1 simply assumes "the schema.sql at the same
+ * level as this file".
+ */
+const SCHEMA_PATH = join(__dirname, 'schema.sql');
+/**
+ * Open SQLite, issue PRAGMAs, and apply the schema idempotently.
+ * - journal_mode=WAL: concurrent read/write (but WAL is unavailable for :memory:, so skip)
+ * - foreign_keys=ON: enable FK constraints
+ * - busy_timeout=5000: wait up to 5s on lock contention (both BEGIN IMMEDIATE and the following PRAGMAs). Set it first
+ */
+export function openDb(opts) {
+    // A file DB cannot be opened by SQLite if its parent directory (default ~/.lockage/; changeable
+    // via LOCKAGE_DB) does not exist. Create it idempotently here. This SQLite is the primary source
+    // of truth for state.
+    if (opts.path !== ':memory:') {
+        const dir = dirname(opts.path);
+        if (dir && dir !== '.')
+            mkdirSync(dir, { recursive: true });
+    }
+    const db = new DatabaseSync(opts.path);
+    const hostId = opts.hostId ?? hostname();
+    // Set busy_timeout first. If set later, while another concurrently started connection is opening/
+    // closing the DB (WAL recovery, etc.), the following journal_mode switch fails immediately with
+    // SQLITE_BUSY instead of waiting. This happens on concurrent startup regardless of migration.
+    db.exec('PRAGMA busy_timeout=5000;');
+    // :memory: does not support WAL. Use WAL only for a file DB.
+    if (opts.path !== ':memory:') {
+        db.exec('PRAGMA journal_mode=WAL;');
+    }
+    db.exec('PRAGMA foreign_keys=ON;');
+    const schema = readFileSync(SCHEMA_PATH, 'utf8');
+    // Apply the issue → ticket rename (#70) before schema.sql. If applied after, CREATE TABLE IF NOT
+    // EXISTS would create an empty tickets first, making the existing issues impossible to rename.
+    migrateIssuesToTickets(db, schema);
+    // Apply the schema idempotently (the CREATE TABLE IF NOT EXISTS group).
+    // New tables such as publish_locks are applied idempotently by schema.sql's CREATE TABLE IF NOT
+    // EXISTS and are created here if absent in an existing DB (brand-new tables, so migrate()'s column
+    // additions are not needed).
+    db.exec(schema);
+    // Idempotent migration for an existing DB. CREATE TABLE IF NOT EXISTS does not add columns to an
+    // existing table, so newly added columns are checked for presence via PRAGMA table_info and ALTERed.
+    migrate(db);
+    return {
+        db,
+        hostId,
+        close() {
+            db.close();
+        },
+    };
+}
+/** Whether a column exists (PRAGMA table_info). */
+function hasColumn(db, table, column) {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return rows.some((r) => r.name === column);
+}
+/** Whether a table exists (sqlite_master). */
+function hasTable(db, table) {
+    return (db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(table) !== undefined);
+}
+function renameColumnIfExists(db, table, from, to) {
+    if (hasTable(db, table) && hasColumn(db, table, from)) {
+        db.exec(`ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to}`);
+    }
+}
+/**
+ * #70: in step with renaming lockage's work unit from issue to ticket, move the existing DB's
+ * tables, columns, and board kinds to the new names (idempotent). Does nothing if issues is absent
+ * (new DB) or tickets already exists.
+ *
+ * FTS5's external-content setting (content='issues') does not follow a table rename, so drop
+ * issues_fts and its triggers, re-create it as tickets_fts via schema.sql, and rebuild the index.
+ * Also drop the old indexes (they would remain rewritten to point at the new column names after the
+ * rename and duplicate the new-named ones that schema.sql creates).
+ *
+ * The rename, applying schema.sql, and rebuilding the index are committed in a single transaction.
+ * If it stops midway, the next startup sees tickets so migration does not run, leaving an empty
+ * tickets_fts. Updating a pre-migration ticket then would make FTS5's delete look for a row absent
+ * from the index and raise SQLITE_CORRUPT_VTAB.
+ *
+ * @param schema the contents of schema.sql (read by the caller).
+ * @returns true if a rename was performed.
+ */
+export function migrateIssuesToTickets(db, schema) {
+    if (!hasTable(db, 'issues') || hasTable(db, 'tickets'))
+        return false;
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        // The pre-lock check may be stale if another concurrently started process finished the migration first.
+        if (!hasTable(db, 'issues') || hasTable(db, 'tickets')) {
+            db.exec('COMMIT');
+            return false;
+        }
+        db.exec(`
+      DROP TRIGGER IF EXISTS issues_ai;
+      DROP TRIGGER IF EXISTS issues_ad;
+      DROP TRIGGER IF EXISTS issues_au;
+      DROP TABLE IF EXISTS issues_fts;
+      DROP INDEX IF EXISTS idx_issues_status;
+      DROP INDEX IF EXISTS idx_issue_repos_repo;
+      DROP INDEX IF EXISTS idx_tasks_issue;
+      ALTER TABLE issues RENAME TO tickets;
+    `);
+        renameColumnIfExists(db, 'tickets', 'issue_ready_at', 'ticket_ready_at');
+        if (hasTable(db, 'issue_repos')) {
+            db.exec(`ALTER TABLE issue_repos RENAME TO ticket_repos`);
+        }
+        renameColumnIfExists(db, 'ticket_repos', 'issue_id', 'ticket_id');
+        renameColumnIfExists(db, 'tasks', 'issue_id', 'ticket_id');
+        renameColumnIfExists(db, 'publish_locks', 'issue_id', 'ticket_id');
+        renameColumnIfExists(db, 'board_messages', 'ref_issue_id', 'ref_ticket_id');
+        if (hasTable(db, 'board_messages')) {
+            // lockage-publish looks at the board's ticket_ready to find tickets awaiting a PR, so move the old kind too.
+            db.exec(`UPDATE board_messages SET kind = 'ticket_ready' WHERE kind = 'issue_ready'`);
+        }
+        db.exec(schema);
+        db.exec(`INSERT INTO tickets_fts(tickets_fts) VALUES ('rebuild')`);
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            /* already closed */
+        }
+        throw e;
+    }
+    return true;
+}
+/**
+ * Backward-compatible migration for an existing DB (idempotent).
+ * - worktree_assignments.repo_path: the FS root of the repo that merge uses for `git -C`. Absent in
+ *   an old DB, so ADD COLUMN (existing rows stay NULL = fall back to the argument at merge time).
+ * - worktree_assignments.base_sha: the fork-point commit SHA, to compute the diff from base later.
+ *   Absent in an old DB, so ADD COLUMN (existing rows stay NULL = the diff side falls back to status only).
+ * - Per-ticket PR (A-1〜A-3): ADD COLUMN for tickets.integration_branch / tickets.ticket_ready_at /
+ *   merge_queue.target_branch / board_messages.ref_ticket_id (all nullable).
+ * - Remove the CHECK (note|handoff|question) on board_messages.kind (option 3). SQLite requires a
+ *   table rebuild to change a CHECK, so if the old CHECK remains in the DDL string, copy to _new and swap.
+ */
+export function migrate(db) {
+    if (!hasColumn(db, 'worktree_assignments', 'repo_path')) {
+        db.exec(`ALTER TABLE worktree_assignments ADD COLUMN repo_path TEXT`);
+    }
+    if (!hasColumn(db, 'worktree_assignments', 'base_sha')) {
+        db.exec(`ALTER TABLE worktree_assignments ADD COLUMN base_sha TEXT`);
+    }
+    // Per-ticket PR additional columns (idempotent)
+    if (!hasColumn(db, 'tickets', 'integration_branch')) {
+        db.exec(`ALTER TABLE tickets ADD COLUMN integration_branch TEXT`);
+    }
+    if (!hasColumn(db, 'tickets', 'ticket_ready_at')) {
+        db.exec(`ALTER TABLE tickets ADD COLUMN ticket_ready_at INTEGER`);
+    }
+    if (!hasColumn(db, 'merge_queue', 'target_branch')) {
+        db.exec(`ALTER TABLE merge_queue ADD COLUMN target_branch TEXT`);
+    }
+    if (!hasColumn(db, 'board_messages', 'ref_ticket_id')) {
+        db.exec(`ALTER TABLE board_messages ADD COLUMN ref_ticket_id TEXT`);
+    }
+    // Issue #49: a question's resolution state (NULL = unresolved). Existing rows stay NULL = backward compatible (readable as unresolved).
+    if (!hasColumn(db, 'board_messages', 'resolved_at')) {
+        db.exec(`ALTER TABLE board_messages ADD COLUMN resolved_at INTEGER`);
+    }
+    if (!hasColumn(db, 'board_messages', 'resolved_by')) {
+        db.exec(`ALTER TABLE board_messages ADD COLUMN resolved_by TEXT`);
+    }
+    migrateBoardKindCheck(db);
+}
+/**
+ * Remove the CHECK constraint on board_messages.kind (option 3). SQLite cannot drop a CHECK via
+ * ALTER, so if the old CHECK (kind IN ...) remains in sqlite_master's DDL string, rebuild the table.
+ * board has only the seq UNIQUE index and no triggers, so _new create → copy → DROP → RENAME →
+ * recreate indexes is safe. A new DB (schema.sql creates it without a CHECK) does not match the DDL and is a no-op.
+ */
+function migrateBoardKindCheck(db) {
+    const row = db
+        .prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='board_messages'`)
+        .get();
+    if (!row || !/CHECK\s*\(\s*kind\s+IN/i.test(row.sql))
+        return; // no CHECK = no rebuild needed
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        // Include ref_ticket_id / resolved_at / resolved_by in the new table too, assuming they already
+        // exist from the ADD COLUMN above (otherwise the new columns vanish the moment an old CHECK-ed DB
+        // is migrated; the Issue #49 pitfall).
+        db.exec(`
+      CREATE TABLE board_messages_new (
+        id            TEXT PRIMARY KEY,
+        seq           INTEGER NOT NULL,
+        author        TEXT NOT NULL,
+        to_agent      TEXT,
+        kind          TEXT NOT NULL DEFAULT 'note',
+        body          TEXT NOT NULL,
+        ref_task_id   TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+        ref_ticket_id TEXT REFERENCES tickets(id) ON DELETE SET NULL,
+        resolved_at   INTEGER,
+        resolved_by   TEXT,
+        created_at    INTEGER NOT NULL,
+        host_id       TEXT NOT NULL,
+        origin        TEXT NOT NULL DEFAULT 'local'
+      );
+      INSERT INTO board_messages_new
+        (id, seq, author, to_agent, kind, body, ref_task_id, ref_ticket_id, resolved_at, resolved_by, created_at, host_id, origin)
+        SELECT id, seq, author, to_agent, kind, body, ref_task_id, ref_ticket_id, resolved_at, resolved_by, created_at, host_id, origin
+          FROM board_messages;
+      DROP TABLE board_messages;
+      ALTER TABLE board_messages_new RENAME TO board_messages;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_board_seq ON board_messages(seq);
+      CREATE INDEX IF NOT EXISTS idx_board_to  ON board_messages(to_agent, seq);
+    `);
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            /* already closed */
+        }
+        throw e;
+    }
+}
+/** unix seconds (integer). All tables' *_at are unified as unix seconds. */
+export function unixNow() {
+    return Math.floor(Date.now() / 1000);
+}
+//# sourceMappingURL=index.js.map

package/dist/db/schema.sql

@@ -0,0 +1,238 @@
+-- =========================================================
+-- coord-dev-mcp schema (per minimal-design.md §3)
+-- Source of truth = local SQLite (WAL). Issue the following PRAGMAs at startup.
+--   PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;
+--
+-- Distribution meta columns are added to every table:
+--   host_id : the originating host (fixed to the local host in Phase 1)
+--   origin  : 'local' | 'synced' | 'candidate' (fixed to 'local' in Phase 1)
+-- =========================================================
+
+-- ---------- tickets: the container for work items (cross-cutting, long-lived, never claimed. model 3) ----------
+CREATE TABLE IF NOT EXISTS tickets (
+    id            TEXT PRIMARY KEY,            -- UUID/ULID
+    title         TEXT NOT NULL,
+    body          TEXT,                        -- body (background / acceptance criteria). Indexed by FTS5
+    status        TEXT NOT NULL DEFAULT 'open' -- open|in_progress|closed
+                     CHECK (status IN ('open','in_progress','closed')),
+    priority      INTEGER NOT NULL DEFAULT 0,  -- larger is higher priority. Ties break by created_at ascending. Negatives allowed (defer). Rough guide -10/0/10/100
+    assignee      TEXT,                        -- assignee (not a claim; just an owner label)
+    version       INTEGER NOT NULL DEFAULT 0,  -- D-4 decided: optimistic lock on body/status (CAS only via update_ticket)
+    integration_branch TEXT,                   -- per-ticket PR: integration branch name (NULL = not yet created). A-2
+    ticket_ready_at INTEGER,                   -- per-ticket PR: time ticket_ready was emitted (NULL = not emitted). CAS prevents double emission. A-3
+    created_by    TEXT,
+    created_at    INTEGER NOT NULL,
+    updated_at    INTEGER NOT NULL,
+    host_id       TEXT NOT NULL,
+    origin        TEXT NOT NULL DEFAULT 'local'
+);
+CREATE INDEX IF NOT EXISTS idx_tickets_status ON tickets(status);
+
+-- ---------- ticket_repos: ticket↔repo cross-cutting (many-to-many, D-1 decided = join table) ----------
+-- Convention: a ticket with no rows = fully cross-cutting (repo-independent). One or more rows = it concerns those repos.
+CREATE TABLE IF NOT EXISTS ticket_repos (
+    ticket_id  TEXT NOT NULL REFERENCES tickets(id) ON DELETE CASCADE,
+    repo       TEXT NOT NULL,
+    host_id    TEXT NOT NULL,
+    origin     TEXT NOT NULL DEFAULT 'local',
+    PRIMARY KEY (ticket_id, repo)
+);
+CREATE INDEX IF NOT EXISTS idx_ticket_repos_repo ON ticket_repos(repo);
+
+-- ---------- tickets_fts: full-text search over ticket bodies (FTS5) ----------
+CREATE VIRTUAL TABLE IF NOT EXISTS tickets_fts USING fts5(
+    title, body,
+    content='tickets',
+    content_rowid='rowid',
+    tokenize='trigram'          -- substring search for Japanese (unicode61 cannot segment CJK)
+);
+CREATE TRIGGER IF NOT EXISTS tickets_ai AFTER INSERT ON tickets BEGIN
+    INSERT INTO tickets_fts(rowid, title, body) VALUES (new.rowid, new.title, new.body);
+END;
+CREATE TRIGGER IF NOT EXISTS tickets_ad AFTER DELETE ON tickets BEGIN
+    INSERT INTO tickets_fts(tickets_fts, rowid, title, body) VALUES ('delete', old.rowid, old.title, old.body);
+END;
+CREATE TRIGGER IF NOT EXISTS tickets_au AFTER UPDATE ON tickets BEGIN
+    INSERT INTO tickets_fts(tickets_fts, rowid, title, body) VALUES ('delete', old.rowid, old.title, old.body);
+    INSERT INTO tickets_fts(rowid, title, body) VALUES (new.rowid, new.title, new.body);
+END;
+
+-- ---------- tasks: the task entity (has a version column for optimistic locking) ----------
+CREATE TABLE IF NOT EXISTS tasks (
+    id            TEXT PRIMARY KEY,
+    ticket_id     TEXT REFERENCES tickets(id) ON DELETE SET NULL,  -- parent ticket (nullable. model 3)
+    repo          TEXT NOT NULL,               -- a task is repo-local (FR-7.4)
+    title         TEXT NOT NULL,
+    description   TEXT,
+    status        TEXT NOT NULL DEFAULT 'open' -- open|in_progress|done|abandoned|blocked
+                     CHECK (status IN ('open','in_progress','done','abandoned','blocked')),
+    assignee      TEXT,                        -- the claiming agent_id (NULL = unclaimed)
+    priority      INTEGER NOT NULL DEFAULT 0,  -- larger is higher priority. Ties break by created_at ascending. Negatives allowed (defer). Rough guide -10/0/10/100
+    version       INTEGER NOT NULL DEFAULT 0,  -- for CAS. +1 on every update
+    heartbeat_at  INTEGER,                     -- last liveness time of the claim holder (unix sec)
+    created_at    INTEGER NOT NULL,
+    updated_at    INTEGER NOT NULL,
+    host_id       TEXT NOT NULL,
+    origin        TEXT NOT NULL DEFAULT 'local'
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_status   ON tasks(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(assignee);
+CREATE INDEX IF NOT EXISTS idx_tasks_ticket   ON tasks(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_repo     ON tasks(repo);
+
+-- ---------- task_edges: the dependency DAG (blocks edges) ----------
+CREATE TABLE IF NOT EXISTS task_edges (
+    from_task  TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    to_task    TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+    kind       TEXT NOT NULL DEFAULT 'blocks' CHECK (kind IN ('blocks')),
+    host_id    TEXT NOT NULL,
+    origin     TEXT NOT NULL DEFAULT 'local',
+    PRIMARY KEY (from_task, to_task)
+);
+CREATE INDEX IF NOT EXISTS idx_edges_to ON task_edges(to_task);
+
+-- ---------- claims: advisory lease over file globs ----------
+CREATE TABLE IF NOT EXISTS claims (
+    id            TEXT PRIMARY KEY,
+    holder        TEXT NOT NULL,               -- agent_id
+    globs         TEXT NOT NULL,               -- JSON array string
+    task_id       TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+    lease_ttl_sec INTEGER NOT NULL DEFAULT 28800,  -- 8h
+    heartbeat_at  INTEGER NOT NULL,
+    expires_at    INTEGER NOT NULL,            -- heartbeat_at + lease_ttl_sec (denormalized)
+    released_at   INTEGER,                     -- explicit release time (NULL = active)
+    created_at    INTEGER NOT NULL,
+    host_id       TEXT NOT NULL,
+    origin        TEXT NOT NULL DEFAULT 'local'
+);
+CREATE INDEX IF NOT EXISTS idx_claims_active  ON claims(released_at, expires_at);
+CREATE INDEX IF NOT EXISTS idx_claims_holder  ON claims(holder);
+
+-- ---------- publish_locks: a per-ticket publish advisory lock (lease/TTL) ----------
+-- An advisory lock that closes the read→act race where two lockage-publish processes pick up
+-- the same ticket simultaneously. It mirrors the lease/TTL design of the claims table (glob lease)
+-- and is acquired/stolen via a BEGIN IMMEDIATE CAS. PK=ticket_id serializes only the same ticket
+-- and does not block other tickets (other tickets in the batch keep being processed). A row with expires_at < now is considered stale and may be stolen.
+CREATE TABLE IF NOT EXISTS publish_locks (
+    ticket_id    TEXT PRIMARY KEY,            -- 1 ticket = 1 lock. Does not block other tickets
+    holder       TEXT NOT NULL,               -- the acquirer token (ulid). Used to authenticate the release
+    acquired_at  INTEGER NOT NULL,            -- acquisition time (unix seconds)
+    expires_at   INTEGER NOT NULL,            -- expiry time (acquired_at + ttl). Past this it may be stolen
+    host_id      TEXT NOT NULL,
+    origin       TEXT NOT NULL DEFAULT 'local'
+);
+CREATE INDEX IF NOT EXISTS idx_publish_locks_expires ON publish_locks(expires_at);
+
+-- ---------- board_messages: the shared board / directed handoff ----------
+CREATE TABLE IF NOT EXISTS board_messages (
+    id           TEXT PRIMARY KEY,
+    seq          INTEGER NOT NULL,             -- a monotonically increasing cursor. Assigned MAX+1 inside BEGIN IMMEDIATE
+    author       TEXT NOT NULL,
+    to_agent     TEXT,
+    -- kind has no CHECK (option 3): the value set will keep growing (note/handoff/question/ticket_ready/…),
+    -- so the app-layer z.enum (src/index.ts) is the single source of truth. Changing a CHECK in SQLite
+    -- requires recreating the table, which is costly each time it grows, so the DB does not constrain it.
+    -- State-machine columns (status/state/edges.kind) are fixed by design, so they are still guarded by a DB CHECK (dividing principle: a growing enum lives in the app layer / a fixed one in the DB).
+    kind         TEXT NOT NULL DEFAULT 'note',
+    body         TEXT NOT NULL,
+    ref_task_id  TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+    ref_ticket_id TEXT REFERENCES tickets(id) ON DELETE SET NULL,  -- a reference pointing at a ticket, e.g. ticket_ready. A-3
+    -- Issue #49: the resolution state of a question. NULL = unresolved / non-NULL = resolved (at that time). resolved_by is
+    -- the resolving actor (auto-resolve = the assignee who set the task to done/abandoned, manual resolve = the agent_id of resolve_question).
+    -- No CHECK (same policy as kind. The source of truth is the app layer: resolve_question rejects anything other than a question).
+    resolved_at  INTEGER,                      -- NULL = unresolved. Used to filter read_board(unresolved_only)
+    resolved_by  TEXT,                          -- the agent_id of the resolving actor (nullable)
+    created_at   INTEGER NOT NULL,
+    host_id      TEXT NOT NULL,
+    origin       TEXT NOT NULL DEFAULT 'local'
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_board_seq ON board_messages(seq);
+CREATE INDEX IF NOT EXISTS idx_board_to  ON board_messages(to_agent, seq);
+
+-- context_entries / context_fts (context tied to git commits) were removed in #69.
+-- Tables left in an existing DB are not DROPped so as not to erase records (harmless since nothing reads or writes them).
+-- Because an old DB still has these names, do not create a table with the same name for another purpose (CREATE TABLE IF NOT EXISTS
+-- would do nothing and keep running with the old column layout).
+
+-- ---------- worktree_assignments: agent↔worktree physical isolation ----------
+CREATE TABLE IF NOT EXISTS worktree_assignments (
+    id             TEXT PRIMARY KEY,
+    agent_id       TEXT NOT NULL,
+    worktree_path  TEXT NOT NULL,              -- 1 worktree = 1 agent (the core of physical isolation)
+    repo_path      TEXT,                       -- the repo's FS root (target of git -C). The merge treats it as the source of truth
+    branch         TEXT NOT NULL,
+    base_sha       TEXT,                       -- the branch-point commit SHA. Used later to compute the diff from base (git diff --name-only <base_sha>...HEAD). NULL for old rows / failed resolution
+    task_id        TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+    status         TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','released')),
+    created_at     INTEGER NOT NULL,
+    released_at    INTEGER,
+    host_id        TEXT NOT NULL,
+    origin         TEXT NOT NULL DEFAULT 'local'
+);
+CREATE INDEX IF NOT EXISTS idx_wt_agent  ON worktree_assignments(agent_id, status);
+-- "1 worktree = 1 agent" applies only to active rows (partial UNIQUE).
+-- A column-level UNIQUE would also make released history unique and conflict with §4.5 "reconnect returns to the same deterministic path"
+-- (you could not re-INSERT the same path). Limiting it to active satisfies both.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_wt_path_active
+    ON worktree_assignments(worktree_path) WHERE status = 'active';
+
+-- ---------- agents: session liveness management (the basis for crash-expiry decisions) ----------
+CREATE TABLE IF NOT EXISTS agents (
+    agent_id      TEXT PRIMARY KEY,
+    label         TEXT,
+    last_seen_at  INTEGER NOT NULL,
+    created_at    INTEGER NOT NULL,
+    host_id       TEXT NOT NULL,
+    origin        TEXT NOT NULL DEFAULT 'local'
+);
+
+-- ---------- dirty_sets: pre-commit change announcement (mutable. FR-1.5. D-2 = per-file) ----------
+CREATE TABLE IF NOT EXISTS dirty_sets (
+    id             TEXT PRIMARY KEY,
+    agent_id       TEXT NOT NULL,
+    worktree_path  TEXT NOT NULL,
+    files          TEXT NOT NULL,              -- JSON array: changed file paths (per file)
+    updated_at     INTEGER NOT NULL,
+    host_id        TEXT NOT NULL,
+    origin         TEXT NOT NULL DEFAULT 'local',
+    UNIQUE (agent_id, worktree_path)           -- one dirty-set row per worktree (overwritten)
+);
+CREATE INDEX IF NOT EXISTS idx_dirty_agent ON dirty_sets(agent_id);
+
+-- ---------- merge_queue: the serial queue for the integration merge gate (FR-1.6) ----------
+CREATE TABLE IF NOT EXISTS merge_queue (
+    id             TEXT PRIMARY KEY,
+    seq            INTEGER NOT NULL,           -- serial processing order. Same numbering discipline as board: MAX+1 inside BEGIN IMMEDIATE
+    agent_id       TEXT NOT NULL,
+    worktree_path  TEXT NOT NULL,
+    branch         TEXT NOT NULL,
+    task_id        TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+    repo           TEXT NOT NULL,
+    state          TEXT NOT NULL DEFAULT 'queued'  -- queued|merging|merged|needs_review
+                      CHECK (state IN ('queued','merging','merged','needs_review')),
+    precheck       TEXT,                        -- 3-way precheck result (JSON)
+    target_branch  TEXT,                        -- per-ticket PR: the aggregation target branch (NULL = base, backward compatible). A-1
+    enqueued_at    INTEGER NOT NULL,
+    processed_at   INTEGER,
+    host_id        TEXT NOT NULL,
+    origin         TEXT NOT NULL DEFAULT 'local'
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_merge_seq   ON merge_queue(seq);
+CREATE INDEX IF NOT EXISTS idx_merge_state ON merge_queue(state, seq);
+
+-- ---------- wakes: the pending queue for A2A wakes (§4.8. non-board wake signals such as overlap) ----------
+-- The board is represented by board_messages (fetched incrementally by the seq cursor), but transient wake signals
+-- that should not be left on the board, such as overlap, are stacked here and consumed by wait_for_unblock.
+-- take_pending_wakes(agent_id, kind) = read the rows with consumed_at IS NULL and mark them consumed.
+CREATE TABLE IF NOT EXISTS wakes (
+    id            TEXT PRIMARY KEY,
+    target        TEXT NOT NULL,               -- the agent_id to wake
+    kind          TEXT NOT NULL                -- overlap|task_ready|board (currently only overlap goes through this table)
+                     CHECK (kind IN ('overlap','task_ready','board')),
+    payload       TEXT,                        -- JSON (originating agent / files, etc.)
+    created_at    INTEGER NOT NULL,
+    consumed_at   INTEGER,                     -- consumed time (NULL = pending)
+    host_id       TEXT NOT NULL,
+    origin        TEXT NOT NULL DEFAULT 'local'
+);
+CREATE INDEX IF NOT EXISTS idx_wakes_pending ON wakes(target, kind, consumed_at);

package/dist/hook/clients.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-client adapters. They call the pure logic in repo.ts / context.ts / guard.ts, parse each
+ * client's input (claude / antigravity / kiro), and build the response. Only the input/output
+ * shapes are client-specific; the decision logic itself stays inside the pure logic.
+ *
+ * The final control of exit codes and stdout/stderr is handled by the outermost shell in
+ * dispatch.ts. Here we decide "what to output", and dispatch.ts handles "how to output it" (write
+ * the JSON to stdout / set the exit code). Rather than returning both side effects (record, stderr
+ * log) and an "output payload", each adapter function returns a value natural to its client.
+ */
+/**
+ * Result of the claude guard. Returns the JSON to write to stdout (null if none). record is already
+ * performed as a side effect. For PreToolUse, if decide returns a reason, an ask JSON, otherwise no
+ * output. For PostToolUse, record and output nothing.
+ */
+export declare function claudeGuard(stdin: string): object | null;
+/**
+ * Result of the claude session. Returns the JSON to write to stdout (null if none).
+ * For SessionStart, no output if repoState(cwd) is null, otherwise buildContext as
+ * additionalContext. For SubagentStart, no output unless agent_type includes lockage-worker, in
+ * which case buildWorkerContext as additionalContext. The output JSON's hookEventName echoes the
+ * input event name.
+ */
+export declare function claudeSession(stdin: string, agentsMd: string): object | null;
+/**
+ * Result of the antigravity guard. Always returns an output JSON (returning nothing is treated as
+ * deny, so always return a decision).
+ * pre: decide null→{decision:'ask'}, with a reason→{decision:'force_ask',reason}.
+ * post: record only when there is no error, always {}.
+ */
+export declare function antigravityGuard(stdin: string, event: 'pre' | 'post'): object;
+/**
+ * Result of the antigravity session. Returns the JSON to inject (injectSteps or {}).
+ * If invocationNum!==0 or already injected, {}; otherwise concatenate buildContext over
+ * workspacePaths in order, deduplicating by repoState→mainRoot??toplevel.
+ */
+export declare function antigravitySession(stdin: string, agentsMd: string): object;
+export declare const KIRO_EXIT_ALLOW = 0;
+export declare const KIRO_EXIT_DENY = 2;
+/**
+ * Decision result of the kiro guard. Returns an exit code. Messages to stderr are emitted inside
+ * this function.
+ * - PostToolUse → exit 0 (a defensive contract; not called by the generated hook)
+ * - path unavailable → exit 0 + stderr warning (the list of tool_input keys)
+ * - mainTreeRoot !== null → exit 2 + stderr message
+ * - otherwise → exit 0
+ * Exceptions (e.g. a git parse error) are made fail-closed (exit 2) by the outermost shell in
+ * dispatch.ts.
+ */
+export declare function kiroGuard(stdin: string): number;
+/**
+ * Result of the kiro session. Returns the text to write to stdout (null if none).
+ * No output if repoState(cwd) is null, otherwise buildContext (KIRO_HEADER) as stdout text.
+ * Appends a self-diagnostic at the end inside the kiro adapter.
+ */
+export declare function kiroSession(stdin: string, agentsMd: string): string | null;