lockage 0.0.0-stage → 0.9.1

package/dist/lockage/git.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A thin wrapper that runs a git command repo-scoped (`git -C <repo>`).
+ * Because of the multi-repo assumption (§3: tasks.repo is required), worktree assignment, the merge
+ * gate, and the 3-way precheck all run in this `git -C <repo>` scope.
+ *
+ * @returns the trimmed stdout string.
+ * @throws  execFileSync throws on a non-zero exit (caught by the caller).
+ *
+ * HIGH-2 mitigation: expand maxBuffer from the default (1MB) to 64MB. For many-file changes,
+ * `diff --name-only` / `merge-tree --write-tree` / `show --name-only` throwing ENOBUFS past 1MB
+ * would (a) permanently stall the merge gate if via threeWayPrecheck, and (b) make gitConflictFiles'
+ * catch misparse the truncated stdout. With a sufficient buffer, this throw does not occur for
+ * realistic inputs.
+ */
+export declare function git(repoPath: string, args: string[]): string;
+/**
+ * Resolve the repo's main branch name (§4.6).
+ * Rather than hardcoding `main`, allow `dev`/`stg`/`master` etc. per repo.
+ *
+ * Phase 1 default policy: explicit value > the first of `dev`/`stg`/`main`/`master` that exists in
+ * the repo > `main`.
+ * (Leaves room to replace with a repo_config table in Phase 2, but for now it is inferred from
+ * existing branches.)
+ */
+export declare function resolveBaseBranch(repoPath: string, explicit?: string): string;
+/**
+ * A best-effort helper that resolves a ref (branch name/tag/commit, etc.) to an existing commit SHA.
+ *
+ * Using `git rev-parse --verify <ref>^{commit}`, it verifies that "the ref exists and reaches a
+ * commit" while folding to a 40-char SHA. Used to record the fork-point SHA at worktree assignment
+ * (to later compute the diff from base `git diff --name-only <base_sha>...HEAD`).
+ *
+ * Like the existing resolveBaseBranch, a best-effort policy that swallows failures: when it cannot
+ * resolve (ref absent, empty repo, before the initial commit, etc.), it returns null instead of
+ * throwing. The caller is designed to save base_sha as NULL when null, and the diff side falls back
+ * to status only when base_sha is absent.
+ */
+export declare function resolveRefSha(repoPath: string, ref: string): string | null;
+/**
+ * A best-effort helper that lists a worktree's working-tree changed files (Issue #52 proposal 2).
+ *
+ * Runs `git status --porcelain -z` against worktreePath (same style as classifyRemoveFailure = take
+ * git status against the worktree path) and extracts the changed file paths from each entry.
+ *
+ * Reasons for using `-z` (NUL-separated):
+ *   - Each entry is terminated with NUL (\0) and the path is not quoted (normal `--porcelain` quotes
+ *     and escapes paths containing spaces etc. with `"..."`, but -z emits them raw).
+ *   - We do not trim the output, so there is no column shift from the leading space left in a
+ *     "worktree-only change ( M path)" or the leading space of the 2nd+ entries (status can be
+ *     stripped at a fixed width).
+ * This way it does not break even with paths containing spaces or multiple ` M` (worktree-only) changes.
+ *
+ * The format of each porcelain v1 -z entry:
+ *   - `XY <path>\0` (X=index state, Y=worktree state; the 3rd char is always a space, the path from
+ *     the 4th char). Untracked is `?? <path>\0`.
+ *   - A rename/copy (R/C) comes as 2 entries: `XY <new>\0<old>\0` (new first, old second). Take the
+ *     new side, which is the current path, and skip the immediately following old entry (a raw path with no status).
+ *
+ * Like the other safe helpers, a best-effort that swallows failures: when git fails (not a repo,
+ * etc.) it returns an empty array (dirty auto-compute is an auxiliary feature, so if it cannot be
+ * obtained, err toward emitting nothing).
+ */
+export declare function workingTreeChangedFiles(worktreePath: string): string[];
+/**
+ * A best-effort helper that lists committed diff files from the fork-point SHA (Issue #52 proposal 3).
+ *
+ * When baseSha is non-NULL, runs `git diff --name-only <baseSha>...HEAD` (3-dot = diff from the merge
+ * base) against worktreePath and returns the changed file names. This also lets "changes committed in
+ * the worktree but not yet in the working tree" be included in dirty (union with workingTreeChangedFiles).
+ *
+ * When baseSha is absent (an old row saved as NULL because FEAT-002 could not resolve it, an empty
+ * repo, etc.) it returns an empty array and falls back to the working-tree state only. Like the other
+ * safe helpers, it also returns an empty array on git failure.
+ */
+export declare function committedChangedFiles(worktreePath: string, baseSha: string | null | undefined): string[];
+/**
+ * Sanitization when embedding agent_id / ticket_id etc. into a worktree path or branch name.
+ * Folds characters problematic for the FS/ref such as slashes and whitespace into '-'.
+ */
+export declare function safeSlug(s: string): string;
+/**
+ * Shortening of ulid/agent_id/ticket_id (for deterministic branch names).
+ *
+ * A ULID is 26 chars = the first 10 are a millisecond timestamp and the remaining 16 are a random
+ * part. Using only the head would make the slugs of "2 IDs generated in the same millisecond"
+ * collide, so distinct things fall into the same deterministic name (worktree path / ticket
+ * integration branch name). To avoid this, add a few chars from the trailing random part to the head
+ * (which keeps chronological sort order) to ensure uniqueness. Inputs of 16 chars or fewer (agent_id,
+ * etc.) are not a collision source, so fold them as-is. Worktree assignment and the ticket
+ * integration branch name share the same function, and the root fix (head 8 + tail 6) applies to both.
+ */
+export declare function short(s: string): string;

package/dist/lockage/git.js

@@ -0,0 +1,183 @@
+import { execFileSync } from 'node:child_process';
+/**
+ * A thin wrapper that runs a git command repo-scoped (`git -C <repo>`).
+ * Because of the multi-repo assumption (§3: tasks.repo is required), worktree assignment, the merge
+ * gate, and the 3-way precheck all run in this `git -C <repo>` scope.
+ *
+ * @returns the trimmed stdout string.
+ * @throws  execFileSync throws on a non-zero exit (caught by the caller).
+ *
+ * HIGH-2 mitigation: expand maxBuffer from the default (1MB) to 64MB. For many-file changes,
+ * `diff --name-only` / `merge-tree --write-tree` / `show --name-only` throwing ENOBUFS past 1MB
+ * would (a) permanently stall the merge gate if via threeWayPrecheck, and (b) make gitConflictFiles'
+ * catch misparse the truncated stdout. With a sufficient buffer, this throw does not occur for
+ * realistic inputs.
+ */
+export function git(repoPath, args) {
+    return execFileSync('git', ['-C', repoPath, ...args], {
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    }).trim();
+}
+/**
+ * An internal helper that runs a git command repo-scoped and returns stdout raw without trimming.
+ *
+ * Normally the trimming `git()` is enough, but when the output itself is meaningful — as with
+ * `git status --porcelain -z` (NUL-separated, a fixed-width 2-char status + space at the head, with
+ * a trailing NUL) — trimming would strip the leading space of a "worktree-only change ( M path)"
+ * line or the trailing NUL and shift parsing. Use this function only on paths that handle raw -z output.
+ *
+ * @returns the raw, untrimmed stdout string.
+ * @throws  execFileSync throws on a non-zero exit (caught by the caller).
+ */
+function gitRaw(repoPath, args) {
+    return execFileSync('git', ['-C', repoPath, ...args], {
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+}
+/**
+ * Resolve the repo's main branch name (§4.6).
+ * Rather than hardcoding `main`, allow `dev`/`stg`/`master` etc. per repo.
+ *
+ * Phase 1 default policy: explicit value > the first of `dev`/`stg`/`main`/`master` that exists in
+ * the repo > `main`.
+ * (Leaves room to replace with a repo_config table in Phase 2, but for now it is inferred from
+ * existing branches.)
+ */
+export function resolveBaseBranch(repoPath, explicit) {
+    if (explicit)
+        return explicit;
+    for (const cand of ['dev', 'stg', 'main', 'master']) {
+        try {
+            git(repoPath, ['show-ref', '--verify', '--quiet', `refs/heads/${cand}`]);
+            return cand;
+        }
+        catch {
+            /* to the next candidate */
+        }
+    }
+    // Fallback when none of the candidates exist. The head of the search order is `dev`, but returning
+    // a nonexistent `dev` would make subsequent git operations fail for sure, so keep `main` as the
+    // conventional name most likely to exist.
+    return 'main';
+}
+/**
+ * A best-effort helper that resolves a ref (branch name/tag/commit, etc.) to an existing commit SHA.
+ *
+ * Using `git rev-parse --verify <ref>^{commit}`, it verifies that "the ref exists and reaches a
+ * commit" while folding to a 40-char SHA. Used to record the fork-point SHA at worktree assignment
+ * (to later compute the diff from base `git diff --name-only <base_sha>...HEAD`).
+ *
+ * Like the existing resolveBaseBranch, a best-effort policy that swallows failures: when it cannot
+ * resolve (ref absent, empty repo, before the initial commit, etc.), it returns null instead of
+ * throwing. The caller is designed to save base_sha as NULL when null, and the diff side falls back
+ * to status only when base_sha is absent.
+ */
+export function resolveRefSha(repoPath, ref) {
+    try {
+        return git(repoPath, ['rev-parse', '--verify', `${ref}^{commit}`]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A best-effort helper that lists a worktree's working-tree changed files (Issue #52 proposal 2).
+ *
+ * Runs `git status --porcelain -z` against worktreePath (same style as classifyRemoveFailure = take
+ * git status against the worktree path) and extracts the changed file paths from each entry.
+ *
+ * Reasons for using `-z` (NUL-separated):
+ *   - Each entry is terminated with NUL (\0) and the path is not quoted (normal `--porcelain` quotes
+ *     and escapes paths containing spaces etc. with `"..."`, but -z emits them raw).
+ *   - We do not trim the output, so there is no column shift from the leading space left in a
+ *     "worktree-only change ( M path)" or the leading space of the 2nd+ entries (status can be
+ *     stripped at a fixed width).
+ * This way it does not break even with paths containing spaces or multiple ` M` (worktree-only) changes.
+ *
+ * The format of each porcelain v1 -z entry:
+ *   - `XY <path>\0` (X=index state, Y=worktree state; the 3rd char is always a space, the path from
+ *     the 4th char). Untracked is `?? <path>\0`.
+ *   - A rename/copy (R/C) comes as 2 entries: `XY <new>\0<old>\0` (new first, old second). Take the
+ *     new side, which is the current path, and skip the immediately following old entry (a raw path with no status).
+ *
+ * Like the other safe helpers, a best-effort that swallows failures: when git fails (not a repo,
+ * etc.) it returns an empty array (dirty auto-compute is an auxiliary feature, so if it cannot be
+ * obtained, err toward emitting nothing).
+ */
+export function workingTreeChangedFiles(worktreePath) {
+    let raw;
+    try {
+        raw = gitRaw(worktreePath, ['status', '--porcelain', '-z']);
+    }
+    catch {
+        return [];
+    }
+    // Split on NUL. The trailing NUL appends an empty last element, so skip empty elements.
+    const entries = raw.split('\0');
+    const out = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.length === 0)
+            continue;
+        // `XY <path>`: the first 2 chars are the XY status, the 3rd char is the separating space, the path from the 4th char.
+        const status = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path.length > 0)
+            out.push(path);
+        // For a rename/copy (R/C), the old side follows as the next entry with no status. Skip it.
+        if (status[0] === 'R' || status[0] === 'C')
+            i++;
+    }
+    return out;
+}
+/**
+ * A best-effort helper that lists committed diff files from the fork-point SHA (Issue #52 proposal 3).
+ *
+ * When baseSha is non-NULL, runs `git diff --name-only <baseSha>...HEAD` (3-dot = diff from the merge
+ * base) against worktreePath and returns the changed file names. This also lets "changes committed in
+ * the worktree but not yet in the working tree" be included in dirty (union with workingTreeChangedFiles).
+ *
+ * When baseSha is absent (an old row saved as NULL because FEAT-002 could not resolve it, an empty
+ * repo, etc.) it returns an empty array and falls back to the working-tree state only. Like the other
+ * safe helpers, it also returns an empty array on git failure.
+ */
+export function committedChangedFiles(worktreePath, baseSha) {
+    if (!baseSha)
+        return [];
+    let out;
+    try {
+        out = git(worktreePath, ['diff', '--name-only', `${baseSha}...HEAD`]);
+    }
+    catch {
+        return [];
+    }
+    return out.split('\n').filter((l) => l.length > 0);
+}
+/**
+ * Sanitization when embedding agent_id / ticket_id etc. into a worktree path or branch name.
+ * Folds characters problematic for the FS/ref such as slashes and whitespace into '-'.
+ */
+export function safeSlug(s) {
+    return s.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+/**
+ * Shortening of ulid/agent_id/ticket_id (for deterministic branch names).
+ *
+ * A ULID is 26 chars = the first 10 are a millisecond timestamp and the remaining 16 are a random
+ * part. Using only the head would make the slugs of "2 IDs generated in the same millisecond"
+ * collide, so distinct things fall into the same deterministic name (worktree path / ticket
+ * integration branch name). To avoid this, add a few chars from the trailing random part to the head
+ * (which keeps chronological sort order) to ensure uniqueness. Inputs of 16 chars or fewer (agent_id,
+ * etc.) are not a collision source, so fold them as-is. Worktree assignment and the ticket
+ * integration branch name share the same function, and the root fix (head 8 + tail 6) applies to both.
+ */
+export function short(s) {
+    const slug = safeSlug(s);
+    if (slug.length <= 16)
+        return slug.slice(0, 10);
+    // Head 8 (time-derived, sortable) + tail 6 (random part, unique). A hyphen also keeps it readable.
+    return `${slug.slice(0, 8)}-${slug.slice(-6)}`;
+}
+//# sourceMappingURL=git.js.map

package/dist/lockage/globs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Path normalization (preprocessing for all functions).
+ * - Normalize to a repo-root-relative POSIX path (`/`-separated).
+ * - Strip `./`, resolve `..`, collapse consecutive slashes, strip the leading `/`.
+ * - Case-sensitive comparison (git basis; macOS's default FS is case-insensitive but git distinguishes).
+ * - Do not follow symlinks (compare by the link's own path) = stay a pure string normalization.
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * Whether 2 glob sets "could point at the same file" (the advisory overlap warning §4.3).
+ * glob×glob intersection is generally non-trivial, so Phase 1 uses a conservative approximation
+ * (false positive = safe side):
+ *   (a) overlap if there is a string-identical glob
+ *   (b) one glob's literal prefix directory is contained in / contains the other (e.g. "src/**" and "src/auth/*.ts")
+ *   (c) one glob matches the other's literal path
+ */
+export declare function globsOverlap(globsA: string[], globsB: string[]): boolean;
+/**
+ * Intersection of two file sets (dirty set vs dirty set §4.4 / 3-way precheck §4.6).
+ * Taken strictly by exact normalized-path match.
+ */
+export declare function fileIntersect(filesA: string[], filesB: string[]): string[];
+/**
+ * Whether a glob set matches any of a file set (the overlap of claim(glob) × dirty(file) §4.4).
+ */
+export declare function globsMatchAny(globs: string[], files: string[]): boolean;

package/dist/lockage/globs.js

@@ -0,0 +1,125 @@
+import { minimatch } from 'minimatch';
+/**
+ * §4.0 shared helpers: glob / file-set intersection decisions.
+ *
+ * Shared by the advisory warning (§4.3), dirty-set overlap (§4.4), and 3-way precheck (§4.6).
+ * Design policy (the asymmetry is the point):
+ *   - The advisory side (globsOverlap / globsMatchAny) errs on the safe side of "false positive over
+ *     miss" (warn-never-block, so the cost of over-warning is small, while a miss directly leads to a
+ *     late discovery of a conflict).
+ *   - The merge gate's fileIntersect takes it strictly by exact normalized-path match (a false
+ *     positive here would be an unnecessary needs_review send-back and would hurt P-1).
+ */
+/** Shared minimatch options (§4.0: dot/nocomment/noext). */
+const MM_OPTS = { dot: true, nocomment: true, noext: true };
+/**
+ * Path normalization (preprocessing for all functions).
+ * - Normalize to a repo-root-relative POSIX path (`/`-separated).
+ * - Strip `./`, resolve `..`, collapse consecutive slashes, strip the leading `/`.
+ * - Case-sensitive comparison (git basis; macOS's default FS is case-insensitive but git distinguishes).
+ * - Do not follow symlinks (compare by the link's own path) = stay a pure string normalization.
+ */
+export function normalizePath(p) {
+    // Backslash (Windows) → slash, collapse consecutive slashes
+    let s = p.replace(/\\/g, '/').replace(/\/+/g, '/');
+    // Strip the leading ./ and /
+    s = s.replace(/^\.?\//, '');
+    // Resolve ./ and ../ per segment
+    const out = [];
+    for (const seg of s.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            // Keep a .. that goes above the root (outside the relative path = kept as-is as a comparison string)
+            if (out.length > 0 && out[out.length - 1] !== '..')
+                out.pop();
+            else
+                out.push('..');
+        }
+        else {
+            out.push(seg);
+        }
+    }
+    return out.join('/');
+}
+function normalizeAll(items) {
+    return items.map(normalizePath);
+}
+/** If a glob has a literal directory prefix, return that prefix (null if none). */
+function literalDirPrefix(glob) {
+    const segs = glob.split('/');
+    const literal = [];
+    for (const seg of segs) {
+        // Cut off at a segment containing a wildcard
+        if (/[*?[\]{}]/.test(seg))
+            break;
+        literal.push(seg);
+    }
+    if (literal.length === 0)
+        return null;
+    return literal.join('/');
+}
+/**
+ * Whether 2 glob sets "could point at the same file" (the advisory overlap warning §4.3).
+ * glob×glob intersection is generally non-trivial, so Phase 1 uses a conservative approximation
+ * (false positive = safe side):
+ *   (a) overlap if there is a string-identical glob
+ *   (b) one glob's literal prefix directory is contained in / contains the other (e.g. "src/**" and "src/auth/*.ts")
+ *   (c) one glob matches the other's literal path
+ */
+export function globsOverlap(globsA, globsB) {
+    const a = normalizeAll(globsA);
+    const b = normalizeAll(globsB);
+    for (const ga of a) {
+        for (const gb of b) {
+            // (a) exact match
+            if (ga === gb)
+                return true;
+            // (c) if one is a literal path, test it against the other glob
+            const gaLiteral = !/[*?[\]{}]/.test(ga);
+            const gbLiteral = !/[*?[\]{}]/.test(gb);
+            if (gbLiteral && minimatch(gb, ga, MM_OPTS))
+                return true;
+            if (gaLiteral && minimatch(ga, gb, MM_OPTS))
+                return true;
+            // (b) containment relationship of literal prefix directories
+            const pa = literalDirPrefix(ga);
+            const pb = literalDirPrefix(gb);
+            if (pa !== null && pb !== null) {
+                if (pa === pb)
+                    return true;
+                if (pa.startsWith(pb + '/') || pb.startsWith(pa + '/'))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Intersection of two file sets (dirty set vs dirty set §4.4 / 3-way precheck §4.6).
+ * Taken strictly by exact normalized-path match.
+ */
+export function fileIntersect(filesA, filesB) {
+    const setB = new Set(normalizeAll(filesB));
+    const out = new Set();
+    for (const f of normalizeAll(filesA)) {
+        if (setB.has(f))
+            out.add(f);
+    }
+    return [...out];
+}
+/**
+ * Whether a glob set matches any of a file set (the overlap of claim(glob) × dirty(file) §4.4).
+ */
+export function globsMatchAny(globs, files) {
+    const gs = normalizeAll(globs);
+    const fs = normalizeAll(files);
+    for (const g of gs) {
+        for (const f of fs) {
+            if (minimatch(f, g, MM_OPTS))
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=globs.js.map

package/dist/lockage/merge.d.ts

@@ -0,0 +1,132 @@
+import { type CoordDb } from '../db/index.js';
+/**
+ * §4.6 Integration merge gate (serialization + 3-way precheck, requirement FR-1.6).
+ *
+ * Serializes the integration of worktree results back into the mainline through a single gate.
+ * Small tasks merge-and-discard immediately (1-C); larger work goes through the serial gate (1-B).
+ * Same "never let them happen at the same time" idea as the claim CAS serialization.
+ * - FR-1.6.1 = serial queue (one row at a time in ascending seq; no concurrent processing while merging)
+ * - FR-1.6.2 = 3-way precheck (files touched by mainline ∩ my dirty set) and the auto/review split
+ * - FR-1.6.3 = combined use of 1-C (immediate merge) and 1-B (serial gate)
+ *
+ * Strict repo scoping: merge-base/diff/merge all run as `git -C <repo>`. The mainline branch name is
+ * resolved via resolveBaseBranch(repo) (infers dev/stg/main/master from what actually exists), assuming multi-repo.
+ *
+ * Phase 1 only goes as far as "detect and send back" for conflicts. Automatic conflict resolution is
+ * not included (heavy and unstable).
+ */
+export interface MergeQueueRow {
+    id: string;
+    seq: number;
+    agent_id: string;
+    worktree_path: string;
+    branch: string;
+    task_id: string | null;
+    repo: string;
+    state: 'queued' | 'merging' | 'merged' | 'needs_review';
+    precheck: string | null;
+    enqueued_at: number;
+    processed_at: number | null;
+    host_id: string;
+    origin: string;
+    /** Aggregation target branch (A-1). NULL = base (backward compatible). When aggregating onto an integration branch, its name. */
+    target_branch: string | null;
+}
+export interface MergeArgs {
+    agentId: string;
+    worktreePath: string;
+    branch: string;
+    repo: string;
+    taskId?: string | null;
+    /** Aggregation target branch (A-1). When omitted, resolveBaseBranch(repo). When aggregating onto an integration branch, its name. */
+    targetBranch?: string | null;
+}
+export interface EnqueueResult {
+    merge_id: string;
+    position: number;
+}
+export interface MergedEntry {
+    task_id: string | null;
+    branch: string;
+    path: '1-B';
+}
+export interface NeedsReviewEntry {
+    task_id: string | null;
+    branch: string;
+    contested: string[];
+    /** Error summary when the git merge actually failed (a precheck false-negative slipping through). */
+    error?: string;
+}
+export interface ProcessResult {
+    merged: MergedEntry[];
+    needs_review: NeedsReviewEntry[];
+    /** Peers notified of needs_review via A2A wake (kind='board') + board handoff. */
+    wake_targets: string[];
+}
+export type OnTaskDoneResult = {
+    ok: true;
+    merged: Array<{
+        task_id: string | null;
+        branch: string;
+        path: '1-B' | '1-C';
+    }>;
+    needs_review: NeedsReviewEntry[];
+    wake_targets: string[];
+} | {
+    ok: false;
+    reason: 'no_active_worktree' | 'branch_is_base' | 'not_assignee' | 'lease_expired';
+    detail: string;
+};
+/**
+ * §4.6 enqueue_merge — push a completed worktree onto the serial merge gate (1-B).
+ * seq follows the same numbering discipline as board (MAX+1 inside BEGIN IMMEDIATE): monotonically
+ * increasing and unique.
+ */
+export declare function enqueueMerge(cdb: CoordDb, item: MergeArgs): EnqueueResult;
+/**
+ * §4.6 process_merge_queue — the serial merge gate (1-B).
+ * Processes one row at a time in ascending seq. If a row is already merging, does not process concurrently.
+ * If the 3-way precheck finds zero conflict candidates, auto-merge; if there are candidates, send it back
+ * as needs_review (no hard block — a human/the assignee resolves it in the worktree).
+ * Uses a while loop rather than tail recursion for the next item (avoids stack overflow on long queues).
+ */
+export declare function processMergeQueue(cdb: CoordDb): ProcessResult;
+/**
+ * §4.6 is_small_task — is it a "small task safe to merge immediately" (the 1-C decision)?
+ * Phase 1 default policy (conservative): only merge immediately when there is no divergence and zero conflict candidates.
+ *   (a) no parent ticket (no ticket_id). With a ticket_id it is false regardless of task count
+ *       (= never take 1-C; always aggregate onto the integration branch via 1-B and always return to base via a PR), and
+ *   (b) base_branch has not advanced past my branch point (mainline unchanged = zero divergence)
+ * If neither holds, route it to 1-B. The real conflict decision is finalized in try_immediate_merge.
+ */
+export declare function isSmallTask(cdb: CoordDb, item: MergeArgs): boolean;
+/**
+ * §4.6 try_immediate_merge — 1-C merge-and-discard immediately.
+ * Runs the same 3-way precheck as the serial gate "on the spot for just one item". If there are zero
+ * conflict candidates, merge immediately, discard the worktree immediately, and set the task done. If
+ * there are candidates, return ok:false and demote to 1-B.
+ * @returns ok = merge success, wake_targets = peers woken by the unblock (empty when ok:false).
+ */
+export declare function tryImmediateMerge(cdb: CoordDb, item: MergeArgs): {
+    ok: boolean;
+    wake_targets: string[];
+};
+/**
+ * §4.6 on_task_done — the entry point of the task_done tool (FR-1.6.3).
+ *
+ * Input validation (misuse prevention; stops accidents where git checkout/merge runs on the main working tree):
+ *   - no_active_worktree if there is no active worktree assignment for (agent_id, worktree_path)
+ *   - branch_is_base if branch equals the base branch (dev/stg/main/master)
+ *   - when task_id is given, not_assignee if the caller is not the assignee (another agent owns it, or
+ *     the worktree assignment is not tied to that task and is not eligible for rescue). If the
+ *     lease-expiry rescue re-claim lost a race and the task is still open and unassigned, lease_expired
+ *
+ * After validation passes: a small task (zero divergence, zero conflict candidates) is merged immediately
+ * via try_immediate_merge (1-C). If there is divergence/conflict candidates, enqueue it on the serial gate
+ * via enqueue_merge and drive it with process_merge_queue (1-B). If the immediate merge hits candidates, it
+ * demotes to 1-B (fall-through). 1-B is always the safety net. On a successful merge, set the task done
+ * (finalizeMergedTask) and wake dependent downstream assignees.
+ */
+export declare function onTaskDone(cdb: CoordDb, item: MergeArgs): OnTaskDoneResult;
+/** The merge queue listing in needs_review / all states (for observation). */
+export declare function listMergeQueue(cdb: CoordDb, state?: MergeQueueRow['state']): MergeQueueRow[];