lockage 0.0.0-stage → 0.9.0

package/dist/launcher/client.d.ts

@@ -0,0 +1,22 @@
+export declare class LockageClient {
+    private client;
+    private transport;
+    /**
+     * @param args.toolsets the toolsets to enable on the server (#65). lockage-publish passes
+     *   ['publisher']. If omitted, the caller environment's LOCKAGE_TOOLSETS is inherited as-is.
+     */
+    constructor(args: {
+        serverEntry: string;
+        dbPath: string;
+        nodePath?: string;
+        toolsets?: string[];
+    });
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private call;
+    /**
+     * The generic path to call any lockage tool. lockage-publish uses this path to call tools such as
+     * read_board / read_ticket / list_tasks / acquire_publish_lock.
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<any>;
+}

package/dist/launcher/client.js

@@ -0,0 +1,57 @@
+/**
+ * The Lockage MCP client for lockage-publish (loosely coupled: it does not import the core and
+ * drives it over stdio instead).
+ *
+ * lockage-publish starts the Lockage server as a **separate process** and calls MCP tools. This
+ * preserves the separation that "even if publish crashes the core ledger is intact" and "the core
+ * does not know about publish".
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+/** Parse a tool result (the JSON in text content). */
+function parseResult(result) {
+    const r = result;
+    if (r.isError) {
+        throw new Error(`lockage tool error: ${r.content?.[0]?.text ?? 'unknown'}`);
+    }
+    const text = r.content?.[0]?.text;
+    if (text == null)
+        throw new Error('lockage tool returned no text content');
+    return JSON.parse(text);
+}
+export class LockageClient {
+    client;
+    transport;
+    /**
+     * @param args.toolsets the toolsets to enable on the server (#65). lockage-publish passes
+     *   ['publisher']. If omitted, the caller environment's LOCKAGE_TOOLSETS is inherited as-is.
+     */
+    constructor(args) {
+        const env = { ...process.env, LOCKAGE_DB: args.dbPath };
+        if (args.toolsets)
+            env.LOCKAGE_TOOLSETS = args.toolsets.join(',');
+        this.transport = new StdioClientTransport({
+            command: args.nodePath ?? process.execPath,
+            args: [args.serverEntry],
+            env,
+        });
+        this.client = new Client({ name: 'lockage-launcher', version: '0.0.0' });
+    }
+    async connect() {
+        await this.client.connect(this.transport);
+    }
+    async close() {
+        await this.client.close().catch(() => { });
+    }
+    async call(name, args) {
+        return parseResult(await this.client.callTool({ name, arguments: args }));
+    }
+    /**
+     * The generic path to call any lockage tool. lockage-publish uses this path to call tools such as
+     * read_board / read_ticket / list_tasks / acquire_publish_lock.
+     */
+    async callTool(name, args = {}) {
+        return this.call(name, args);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/launcher/publish-adapter.d.ts

@@ -0,0 +1,88 @@
+/** The PR/MR state (the forge-independent normalized form). */
+export type PrState = 'OPEN' | 'MERGED' | 'CLOSED';
+/** The minimal PR info returned by findPrByHead / openPr. */
+export interface PrRef {
+    number: number;
+    state: PrState;
+    url: string;
+}
+/**
+ * Indicates that openPr could not create a PR because there is "no diff from base".
+ * The caller (publishReadyTickets) folds this into a per-ticket skip (does not crash the loop).
+ */
+export declare class PublishNoDiffError extends Error {
+    readonly head: string;
+    readonly base: string;
+    constructor(head: string, base: string);
+}
+/**
+ * Provider-independent publish operations. github=gh / gitlab=glab are handled through the same
+ * interface. design v1 §3 point 4.
+ */
+export interface PublishAdapter {
+    readonly id: 'github' | 'gitlab';
+    /** Push the integration branch to the remote (a feature-branch push = not protected). */
+    pushBranch(repo: string, branch: string): Promise<void>;
+    /** Create a PR/MR and return the number and URL. The body goes via a tmp file (--body-file). */
+    openPr(args: {
+        repo: string;
+        base: string;
+        head: string;
+        title: string;
+        bodyFile: string;
+    }): Promise<PrRef>;
+    /**
+     * ★ The key to idempotency (design v1 §3 point 5-2). Find an existing PR tied to the head branch.
+     * Prevents double creation even if there is no pr_opened on the board (crash resilience). null if none.
+     */
+    findPrByHead(repo: string, branch: string): Promise<PrRef | null>;
+    /** Look up the current state from the PR number (merge detection = the cleanup trigger). */
+    prState(repo: string, number: number): Promise<PrState>;
+    /** Delete the remote integration branch (post-merge cleanup). */
+    deleteRemoteBranch(repo: string, branch: string): Promise<void>;
+}
+/**
+ * The GitHub implementation (Phase 1's first provider). Delegated to the gh CLI's existing login.
+ * push / deletion use git(); PR operations use gh.
+ */
+export declare class GithubPublishAdapter implements PublishAdapter {
+    private readonly ghCmd;
+    readonly id: "github";
+    /** Allow the gh executable to be swapped in tests/environments (default 'gh'). */
+    constructor(ghCmd?: string);
+    /** Run gh repo-scoped (resolving owner/repo from the CWD's origin remote). */
+    private gh;
+    pushBranch(repo: string, branch: string): Promise<void>;
+    openPr(args: {
+        repo: string;
+        base: string;
+        head: string;
+        title: string;
+        bodyFile: string;
+    }): Promise<PrRef>;
+    findPrByHead(repo: string, branch: string): Promise<PrRef | null>;
+    prState(repo: string, number: number): Promise<PrState>;
+    deleteRemoteBranch(repo: string, branch: string): Promise<void>;
+}
+/**
+ * GitLab stub (not implemented in Phase 1; glab implementation in #4).
+ * design v1 §3 point 4 / D-B4. Satisfies only the interface and fails explicitly if called.
+ */
+export declare class GitlabPublishAdapter implements PublishAdapter {
+    readonly id: "gitlab";
+    private notImplemented;
+    pushBranch(): Promise<void>;
+    openPr(): Promise<PrRef>;
+    findPrByHead(): Promise<PrRef | null>;
+    prState(): Promise<PrState>;
+    deleteRemoteBranch(): Promise<void>;
+}
+/**
+ * Determine the provider from the origin remote's URL (design v1 §3 point 4).
+ * An explicit value takes precedence. github.com→github / gitlab→gitlab.
+ */
+export declare function detectProvider(repoPath: string, explicit?: 'github' | 'gitlab'): 'github' | 'gitlab';
+/** Create a PublishAdapter from the provider. */
+export declare function makePublishAdapter(provider: 'github' | 'gitlab', opts?: {
+    ghCmd?: string;
+}): PublishAdapter;

package/dist/launcher/publish-adapter.js

@@ -0,0 +1,233 @@
+/**
+ * The ③ publish adapter (problem B, B-1) — abstracts integration-branch push and PR/MR operations
+ * in a provider-independent way.
+ *
+ * design v1 §3 point 4 / §4.1. In line with NFR-11 (assumes GitHub/GitLab), it cuts a thin
+ * abstraction in the same style as ToolAdapter. To uphold "the core does not publish"
+ * (requirements-v1 §4.2), the publish/PR operations live here (the launcher), not in the core.
+ *
+ * - push / branch deletion are `git -C <repo>` scoped (reusing git() from src/lockage/git.ts).
+ * - PR operations are delegated to the existing login of the forge CLI (gh / glab) (lockage does not
+ *   handle tokens).
+ * - Safety policy (lessons): push writes the branch name as a literal. No shell variable expansion
+ *   or heredoc fusion. execFileSync passes argv directly, so it does not go through a shell and does
+ *   not take a git-publish-floor shape.
+ */
+import { execFileSync } from 'node:child_process';
+import { git } from '../lockage/git.js';
+/**
+ * Indicates that openPr could not create a PR because there is "no diff from base".
+ * The caller (publishReadyTickets) folds this into a per-ticket skip (does not crash the loop).
+ */
+export class PublishNoDiffError extends Error {
+    head;
+    base;
+    constructor(head, base) {
+        super(`no commits between ${base} and ${head} (nothing to open a PR for)`);
+        this.head = head;
+        this.base = base;
+        this.name = 'PublishNoDiffError';
+    }
+}
+/** Extract the message string from an exception (execFileSync carries stdout/stderr). */
+function errText(e) {
+    const err = e;
+    const parts = [err?.stderr?.toString(), err?.stdout?.toString(), err?.message];
+    return parts.filter(Boolean).join('\n');
+}
+/** Normalize the raw gh/glab state string into a PrState. */
+function normalizeState(raw) {
+    const s = raw.trim().toUpperCase();
+    if (s === 'MERGED')
+        return 'MERGED';
+    if (s === 'CLOSED')
+        return 'CLOSED';
+    // OPEN / '' / unknown are treated as OPEN (safe side, since cleanup triggers only on MERGED).
+    return 'OPEN';
+}
+/**
+ * The GitHub implementation (Phase 1's first provider). Delegated to the gh CLI's existing login.
+ * push / deletion use git(); PR operations use gh.
+ */
+export class GithubPublishAdapter {
+    ghCmd;
+    id = 'github';
+    /** Allow the gh executable to be swapped in tests/environments (default 'gh'). */
+    constructor(ghCmd = 'gh') {
+        this.ghCmd = ghCmd;
+    }
+    /** Run gh repo-scoped (resolving owner/repo from the CWD's origin remote). */
+    gh(repoPath, args) {
+        return execFileSync(this.ghCmd, args, {
+            cwd: repoPath, // gh resolves owner/repo from the CWD's git remote
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+        }).trim();
+    }
+    async pushBranch(repo, branch) {
+        // Branch name written as a literal. execFileSync passes argv directly, so it does not go through
+        // shell expansion. On an existing-PR update (fix option A) this push makes the PR auto-follow too
+        // (the integration branch is derived from base and only appended to, so it is a fast-forward and
+        // does not need force).
+        git(repo, ['push', 'origin', branch]);
+    }
+    async openPr(args) {
+        // On success, gh pr create returns the created PR's URL on a single stdout line.
+        // On failure it exits non-zero and throws. Normalize the 2 cases hit in practice so the caller
+        // can fold them:
+        //   (a) a PR with the same head is already open (a race with findPrByHead) → return the existing PR (= idempotent)
+        //   (b) no diff from base (empty aggregation / already merged) → throw PublishNoDiffError
+        let url;
+        try {
+            url = this.gh(args.repo, [
+                'pr',
+                'create',
+                '--base',
+                args.base,
+                '--head',
+                args.head,
+                '--title',
+                args.title,
+                '--body-file',
+                args.bodyFile,
+            ]);
+        }
+        catch (e) {
+            const msg = errText(e);
+            // (a) already exists: re-fetch and return the existing PR (do not create a duplicate)
+            if (/already exists/i.test(msg)) {
+                const existing = await this.findPrByHead(args.repo, args.head);
+                if (existing)
+                    return existing;
+            }
+            // (b) no diff: distinguish with a dedicated error so it can be cleaned up / skipped
+            if (/No commits between|No commits/i.test(msg)) {
+                throw new PublishNoDiffError(args.head, args.base);
+            }
+            throw e; // anything else is unexpected; the caller (per-ticket try/catch) catches it per ticket
+        }
+        // Right after creation, re-fetch by head to confirm the number/state (absorbs forge differences where the number is not available from the URL alone).
+        const created = await this.findPrByHead(args.repo, args.head);
+        if (created)
+            return created;
+        // Fallback: pick up the number at the end of the URL (even if findPrByHead is empty, creation did succeed).
+        const m = url.match(/\/(\d+)(?:[/?#].*)?$/);
+        const number = m ? Number(m[1]) : 0;
+        if (number === 0) {
+            // Not getting a number is a sign of an anomaly (the URL is valid but findPrByHead is also empty). Warn instead of swallowing.
+            console.error(`[publish] openPr: could not identify the PR number (head=${args.head}, url=${url})`);
+        }
+        return { number, state: 'OPEN', url };
+    }
+    async findPrByHead(repo, branch) {
+        // gh pr list --head <branch> --json number,state,url --state all --limit 1
+        // --state all also picks up MERGED/CLOSED (idempotent = do not re-create even if already merged).
+        // Note: --head matches the head *ref name*. In Phase 1 it is safe because it is the own
+        //       repository and the integration branch name is ULID-derived and unique, but there is room
+        //       for false positives with PRs from a fork or environments with same-named branches
+        //       (if Phase 2 handles forks, the head owner must also be checked).
+        const raw = this.gh(repo, [
+            'pr',
+            'list',
+            '--head',
+            branch,
+            '--state',
+            'all',
+            '--json',
+            'number,state,url',
+            '--limit',
+            '1',
+        ]);
+        if (!raw)
+            return null;
+        let arr;
+        try {
+            arr = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (!Array.isArray(arr) || arr.length === 0)
+            return null;
+        const pr = arr[0];
+        return { number: pr.number, state: normalizeState(pr.state), url: pr.url };
+    }
+    async prState(repo, number) {
+        const raw = this.gh(repo, ['pr', 'view', String(number), '--json', 'state']);
+        try {
+            const obj = JSON.parse(raw);
+            return normalizeState(obj.state ?? '');
+        }
+        catch {
+            return 'OPEN';
+        }
+    }
+    async deleteRemoteBranch(repo, branch) {
+        git(repo, ['push', 'origin', '--delete', branch]);
+    }
+}
+/**
+ * GitLab stub (not implemented in Phase 1; glab implementation in #4).
+ * design v1 §3 point 4 / D-B4. Satisfies only the interface and fails explicitly if called.
+ */
+export class GitlabPublishAdapter {
+    id = 'gitlab';
+    notImplemented() {
+        throw new Error('GitlabPublishAdapter is not implemented yet (Phase1=github only, see design D-B4 / issue #4)');
+    }
+    async pushBranch() {
+        this.notImplemented();
+    }
+    async openPr() {
+        this.notImplemented();
+    }
+    async findPrByHead() {
+        this.notImplemented();
+    }
+    async prState() {
+        this.notImplemented();
+    }
+    async deleteRemoteBranch() {
+        this.notImplemented();
+    }
+}
+/**
+ * Determine the provider from the origin remote's URL (design v1 §3 point 4).
+ * An explicit value takes precedence. github.com→github / gitlab→gitlab.
+ */
+export function detectProvider(repoPath, explicit) {
+    if (explicit)
+        return explicit;
+    let url = '';
+    try {
+        url = git(repoPath, ['remote', 'get-url', 'origin']);
+    }
+    catch {
+        return 'github'; // when the remote is unknown, default to github (Phase 1's first provider)
+    }
+    // Decide on the host part only (so a github repo whose path contains 'gitlab' is not misfired).
+    // Supported forms: git@gitlab.com:org/repo.git / https://gitlab.example.com/org/repo(.git) / ssh://git@gitlab…/…
+    const host = extractHost(url);
+    if (/gitlab/i.test(host))
+        return 'gitlab';
+    return 'github';
+}
+/** Extract the host part from a remote URL (scp-like / https / ssh). Empty string on failure. */
+function extractHost(url) {
+    // scp-like: git@host:org/repo.git
+    const scp = url.match(/^[^/@]+@([^:/]+):/);
+    if (scp)
+        return scp[1];
+    // URL-like: scheme://[user@]host[:port]/...
+    const m = url.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^:/]+)/i);
+    if (m)
+        return m[1];
+    return '';
+}
+/** Create a PublishAdapter from the provider. */
+export function makePublishAdapter(provider, opts) {
+    if (provider === 'gitlab')
+        return new GitlabPublishAdapter();
+    return new GithubPublishAdapter(opts?.ghCmd);
+}
+//# sourceMappingURL=publish-adapter.js.map

package/dist/launcher/publish-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/launcher/publish-cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * lockage-publish — the ③ publish CLI (problem B, B-4).
+ *
+ * A 1-shot command that publishes unprocessed ticket_ready (push the integration branch + create a
+ * PR) and reconciles merged PRs (clean up the integration branch + reset integration_branch to
+ * NULL). It can be called from cron, an orchestrator, or by hand. Since "the core does not publish",
+ * it is a separate bin from the main binary (the lockage MCP server).
+ *
+ * Usage:
+ *   lockage-publish --repo-path <abs> [--mode both|publish|reconcile]
+ *                   [--ticket <id>] [--base <branch>] [--provider github|gitlab]
+ *                   [--agent-id publisher] [--db <path>] [--server-entry <p>]
+ *
+ * Defaults:
+ *   --mode          : both (run publish → reconcile in order; the natural sweep for periodic runs)
+ *   --base          : resolveBaseBranch(repo) (infer dev/stg/main/master from what exists)
+ *   --provider      : determined from the origin remote's host (github by default)
+ *   --agent-id      : "publisher" (the author of pr_opened/pr_merged)
+ *   --db            : $LOCKAGE_DB → ~/.lockage/lockage.sqlite (the cross-repo ledger)
+ *   --server-entry  : the index.js in the same dist as this CLI
+ */
+import { parseArgs } from 'node:util';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveBaseBranch } from '../lockage/git.js';
+import { LockageClient } from './client.js';
+import { publishReadyTickets, reconcileMergedPrs } from './publish.js';
+import { makePublishAdapter, detectProvider } from './publish-adapter.js';
+const USAGE = `lockage-publish — turn ticket_ready into PRs and clean up merged PRs (problem B)\n\n` +
+    `Required:\n` +
+    `  --repo-path <abs>     absolute path to the local repo where the integration branch exists\n\n` +
+    `Optional:\n` +
+    `  --mode <m>            both (default) | publish | reconcile\n` +
+    `  --ticket <id>         process only this ticket (omit to process all unprocessed)\n` +
+    `  --base <branch>       the PR base (inferred via resolveBaseBranch if omitted)\n` +
+    `  --provider <p>        github (default) | gitlab (auto-detected from the origin host)\n` +
+    `  --agent-id <id>       the author of pr_opened/pr_merged (default publisher)\n` +
+    `  --db <path>           the cross-repo ledger (default $LOCKAGE_DB → ~/.lockage/lockage.sqlite)\n` +
+    `  --server-entry <p>    the lockage server's dist/index.js (default: bundled)\n`;
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            'repo-path': { type: 'string' },
+            mode: { type: 'string', default: 'both' },
+            ticket: { type: 'string' },
+            base: { type: 'string' },
+            provider: { type: 'string' },
+            'agent-id': { type: 'string', default: 'publisher' },
+            db: { type: 'string' },
+            'server-entry': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const mode = values.mode ?? 'both';
+    if (values.help ||
+        !values['repo-path'] ||
+        (mode !== 'both' && mode !== 'publish' && mode !== 'reconcile')) {
+        process.stderr.write(USAGE);
+        process.exitCode = values.help ? 0 : 2;
+        return;
+    }
+    const repoPath = resolve(values['repo-path']);
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/launcher
+    const serverEntry = values['server-entry']
+        ? resolve(values['server-entry'])
+        : join(here, '..', 'index.js'); // dist/index.js
+    const dbPath = values.db ?? process.env.LOCKAGE_DB ?? join(homedir(), '.lockage', 'lockage.sqlite');
+    const agentId = values['agent-id'];
+    const provider = values.provider === 'github' || values.provider === 'gitlab'
+        ? values.provider
+        : detectProvider(repoPath);
+    const adapter = makePublishAdapter(provider);
+    // base is only needed for publish. Explicit > resolveBaseBranch(repo).
+    let base = values.base;
+    if (!base) {
+        try {
+            base = resolveBaseBranch(repoPath);
+        }
+        catch {
+            base = 'main';
+        }
+    }
+    const client = new LockageClient({ serverEntry, dbPath, toolsets: ['publisher'] });
+    await client.connect();
+    const result = { provider, mode, repoPath };
+    let hadFailure = false;
+    try {
+        if (mode === 'both' || mode === 'publish') {
+            const published = await publishReadyTickets(client, adapter, {
+                repoPath,
+                base: base,
+                agentId,
+                onlyTicket: values.ticket,
+            });
+            result.published = published;
+            if (published.some((o) => o.result === 'failed'))
+                hadFailure = true;
+        }
+        if (mode === 'both' || mode === 'reconcile') {
+            const reconciled = await reconcileMergedPrs(client, adapter, {
+                repoPath,
+                agentId,
+                onlyTicket: values.ticket,
+            });
+            result.reconciled = reconciled;
+            if (reconciled.some((o) => o.result === 'failed'))
+                hadFailure = true;
+        }
+    }
+    finally {
+        await client.close();
+    }
+    process.stdout.write(JSON.stringify(result) + '\n');
+    // Non-zero if there is at least one per-ticket failure (so cron can detect an anomaly).
+    process.exitCode = hadFailure ? 1 : 0;
+}
+main().catch((e) => {
+    process.stderr.write(`lockage-publish fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=publish-cli.js.map

package/dist/launcher/publish.d.ts

@@ -0,0 +1,140 @@
+import type { LockageClient } from './client.js';
+import { type PublishAdapter } from './publish-adapter.js';
+/** The ticket returned by read_ticket (the minimal fields problem B references). */
+interface TicketView {
+    id: string;
+    title: string;
+    body: string | null;
+    integration_branch: string | null;
+    ticket_ready_at: number | null;
+}
+/** The task returned by list_tasks (the minimal fields used in the PR body list). */
+interface TaskView {
+    id: string;
+    title: string;
+    ticket_id: string | null;
+}
+/** The processing result of one ticket (for logs/tests). */
+export type PublishOutcome = {
+    ticketId: string;
+    result: 'published';
+    prNumber: number;
+    url: string;
+} | {
+    ticketId: string;
+    result: 'already_opened' | 'existing_pr';
+    prNumber?: number;
+    url?: string;
+} | {
+    ticketId: string;
+    result: 'updated';
+    branch: string;
+} | {
+    ticketId: string;
+    result: 'skipped';
+    reason: 'no_branch' | 'branch_not_local' | 'no_diff' | 'locked';
+} | {
+    ticketId: string;
+    result: 'failed';
+    error: string;
+};
+export interface PublishArgs {
+    /** Absolute path to the local repo where the integration branch exists. */
+    repoPath: string;
+    /** The PR base branch. If omitted, the caller (CLI) resolves it via resolveBaseBranch and passes it. */
+    base: string;
+    /** The publisher's agent_id (the author of pr_opened). */
+    agentId: string;
+    /** Process only this ticket (manual/test). Omit to process all unprocessed ticket_ready. */
+    onlyTicket?: string;
+    /** Whether the integration branch exists locally (§3 point 9). For test substitution. Default = git show-ref. */
+    localBranchExists?: (repoPath: string, branch: string) => boolean;
+}
+/** Build the PR body (§3 point 7; Phase 1 omits Closes = recommended scope D-B2). */
+export declare function renderPrBody(ticket: TicketView, tasks: TaskView[]): string;
+/**
+ * Publish unprocessed ticket_ready (the implementation of the §4.4 pseudocode).
+ * With board's pr_opened as the source of truth, skip tickets that already have a PR.
+ * @returns the processing result of each ticket (for logs/tests).
+ */
+export declare function publishReadyTickets(client: LockageClient, adapter: PublishAdapter, args: PublishArgs): Promise<PublishOutcome[]>;
+/**
+ * The post-merge close result of a ticket (reconcile's MERGED path).
+ *   - 'closed'        : an open/in_progress ticket was flipped to closed.
+ *   - 'already_closed': already closed (= do nothing).
+ *   - 'not_found'     : close_ticket_on_merge could not fetch the ticket (rare, since read_ticket just ran).
+ *
+ * close is done via a dedicated path that does not bump the version (close_ticket_on_merge /
+ * closeTicketOnMerge), so a version-CAS conflict cannot occur structurally (there is no conflict result).
+ */
+export type TicketCloseResult = 'closed' | 'already_closed' | 'not_found';
+/** The per-ticket result of reconcileMergedPrs (for logs/tests). */
+export type ReconcileOutcome = {
+    ticketId: string;
+    prNumber: number;
+    result: 'merged';
+    branchDeleted: boolean;
+    cleared: boolean;
+    /** The result of closing the ticket after merge (fix: do not leave merged work open). */
+    ticketClosed: TicketCloseResult;
+    /** #32: number of done-task worktrees under the ticket that were released (successful removes). */
+    worktreesReleased: number;
+    /** Issue #45: number of claims tied to done / abandoned tasks under the ticket that were released. */
+    claimsReleased: number;
+} | {
+    ticketId: string;
+    prNumber: number;
+    result: 'still_open';
+} | {
+    ticketId: string;
+    prNumber: number;
+    result: 'skipped_unmerged_tasks';
+} | {
+    ticketId: string;
+    prNumber: number;
+    result: 'failed';
+    error: string;
+} | {
+    ticketId: string;
+    result: 'skipped';
+    reason: 'no_pr_number' | 'locked';
+};
+/**
+ * Merge-detection cleanup (problem B, B-3, design v1 §3 point 6).
+ * For tickets that are "pr_opened ∧ not pr_merged", check prState and, only for MERGED ones:
+ *   ① delete the remote integration branch (deleteRemoteBranch)
+ *   ② delete the local integration branch (git branch -D, best effort)
+ *   ③ reset tickets.integration_branch to NULL (clear_integration_branch, with the expected_branch guard)
+ *   ④' update tickets.status to closed (close_ticket_on_merge; a dedicated path that does not bump
+ *      the version flips status one-way to closed = no version conflict. Does not leave merged work
+ *      in list_tickets(status:"open"). Does nothing if already closed)
+ *   ④ post pr_merged(ref_ticket_id) to the board ← this ticket is not re-processed afterward (the source of truth for idempotency)
+ * The skipped_unmerged_tasks path (unfinished tasks remain) does not do ③④'④ (= the ticket is not closed).
+ * It does not merge itself (that is a human/CI). No immediacy is needed = reclaim in bulk on the next run.
+ */
+export declare function reconcileMergedPrs(client: LockageClient, adapter: PublishAdapter, args: {
+    repoPath: string;
+    agentId: string;
+    onlyTicket?: string;
+    /** Local branch deletion function (for test substitution). Default = git branch -D. */
+    deleteLocalBranch?: (repoPath: string, branch: string) => boolean;
+}): Promise<ReconcileOutcome[]>;
+/**
+ * Set the ticket to closed after merge (called only from reconcile's MERGED path).
+ *
+ * close is done via the dedicated path close_ticket_on_merge (the core's closeTicketOnMerge) that
+ * does not bump the version. With the same idea as clearIntegrationBranch (D-B1), it aligns
+ * reconcile's cleanup (integration_branch release / status close) symmetrically as "system
+ * operations that do not bump the version". As a result:
+ *   - A local CAS that flips status one-way to closed (WHERE status != 'closed'), so a version
+ *     conflict cannot occur structurally (= no conflict retry). It also does not steal the version
+ *     of a human/other agent's concurrent edit (body, etc.).
+ *   - Does nothing if already closed (changes==0) → 'already_closed'.
+ *   - A missing ticket is 'not_found' (rarely reached since reconcile just ran read_ticket).
+ *
+ * The source of truth for idempotency remains the pr_merged posted by the caller reconcile. Since
+ * pr_merged is posted regardless of whether close succeeds, this ticket is dropped from reconcile
+ * targets on the next run, and no double close/cleanup happens.
+ */
+export declare function closeTicketAfterMerge(client: LockageClient, ticketId: string): Promise<TicketCloseResult>;
+export {};