lockage 0.0.0-stage → 0.9.0

package/dist/lockage/claim.d.ts

@@ -0,0 +1,307 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type CoordDb } from '../db/index.js';
+export declare const TASK_LEASE_SEC: number;
+export interface Task {
+    id: string;
+    ticket_id: string | null;
+    repo: string;
+    title: string;
+    description: string | null;
+    status: 'open' | 'in_progress' | 'done' | 'abandoned' | 'blocked';
+    assignee: string | null;
+    priority: number;
+    version: number;
+    heartbeat_at: number | null;
+    created_at: number;
+    updated_at: number;
+    host_id: string;
+    origin: string;
+}
+export type ClaimResult = {
+    ok: true;
+    task: Task;
+} | {
+    ok: false;
+    reason: 'conflict' | 'not_found';
+    current?: Pick<Task, 'assignee' | 'status' | 'version'>;
+};
+/**
+ * Create a task. ticket_id is nullable (model 3: minor tasks without a ticket are allowed).
+ * Passing depends_on adds edges to the dependency DAG (blocks). It cycle-checks before adding edges
+ * and rejects depends_on that would form a cycle with { ok:false, reason:'cycle' } (§4.8 DAG invariant).
+ */
+export interface CycleError {
+    ok: false;
+    reason: 'cycle';
+    detail: string;
+}
+export declare function createTask(cdb: CoordDb, args: {
+    repo: string;
+    title: string;
+    description?: string;
+    ticketId?: string | null;
+    priority?: number;
+}): Task;
+export declare function createTask(cdb: CoordDb, args: {
+    repo: string;
+    title: string;
+    description?: string;
+    ticketId?: string | null;
+    priority?: number;
+    dependsOn: string[];
+}): Task | CycleError;
+export type AddDependencyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'cycle' | 'not_found' | 'self';
+    detail: string;
+};
+/**
+ * Add a dependency (blocks) edge between existing tasks: fromTask blocks toTask
+ * (= toTask waits for fromTask to finish). The after-the-fact version of create_task(depends_on).
+ * It cycle-checks before adding the edge and rejects with reason:'cycle' if it would form a cycle (§4.8 DAG invariant).
+ */
+export declare function addDependency(cdb: CoordDb, fromTask: string, toTask: string): AddDependencyResult;
+/** Fetch one (undefined if it does not exist). */
+export declare function getTask(db: DatabaseSync, id: string): Task | undefined;
+/** List of open tasks (priority descending → creation order). The client reads version and passes it to claim. */
+export interface ListTasksArgs {
+    status?: Task['status'];
+    assignee?: string;
+    ticketId?: string;
+    repo?: string;
+    readyOnly?: boolean;
+}
+/**
+ * §2.1 list_tasks — list tasks (priority descending → creation order).
+ * Filter by status/assignee/ticket_id/repo. With ready_only=true, return only tasks whose
+ * from_task blockers are all done (unblocked).
+ * When status='blocked', return each row in listBlockedTasks' shape (with blocked_age_sec, etc.).
+ *
+ * The ready decision is the same logic as board.isReady, but it is kept locally here to avoid a
+ * claim.ts→board.ts import cycle (because board.ts imports claim.sweepExpired).
+ */
+export declare function listTasks(cdb: CoordDb, args: ListTasksArgs & {
+    status: 'blocked';
+}): BlockedTaskView[];
+export declare function listTasks(cdb: CoordDb, args?: ListTasksArgs): Task[];
+/**
+ * §4.1 atomic claim — SQLite CAS.
+ * Take an immediate write lock with BEGIN IMMEDIATE, put all current-value conditions in WHERE, and
+ * treat changes==0 as a conflict. expected_version also detects the "someone touched it between read
+ * and claim" conflict.
+ */
+export declare function claimTask(cdb: CoordDb, taskId: string, agentId: string, expectedVersion: number): ClaimResult;
+/**
+ * Explicit release. Only the claim holder can transition (the assignee match is a CAS condition).
+ * outcome='open' (default) = return to open (abandon so it can be re-claimed).
+ * outcome='abandoned'      = make it abandoned (no longer worked on; not a re-claim target).
+ * The done transition is a separate path (the merge gate = task_done), so it is not handled here.
+ */
+export declare function releaseTask(cdb: CoordDb, taskId: string, agentId: string, outcome?: 'open' | 'abandoned'): {
+    ok: boolean;
+};
+/**
+ * §4.x block_task — suspend to wait for a human decision (in_progress → blocked).
+ *
+ * Called before exiting when a headless worker cannot finish due to lacking permission / waiting for
+ * a design decision, etc. The decisive difference from release_task (return to open) / complete_task
+ * (done) is that it **keeps the assignee and heartbeat_at**: even suspended, it leaves "who got stuck
+ * in which worktree" in the state and preserves the worktree (assignment continuity = option (b)).
+ *
+ * blocked is excluded from the lease sweep (sweepExpired reclaims only status='in_progress'), so even
+ * if the worker process dies and heartbeat stops, it is **kept indefinitely** (the machine does not
+ * return it on its own). It is returned only by a human-decided resume_task (same-agent resume) /
+ * handoff (hand to another worker) / release_task (abandoned = cancel).
+ *
+ * The stuck reason is externalized to the board (post_board kind='question', ref_task_id) rather than
+ * adding a column to the task itself. Worker convention: leave the question first, then call
+ * block_task (since heartbeat stops at blocked, if it dies before writing the reason the way it got stuck is unknown).
+ *
+ * CAS: conditioned on "assignee = agentId and status = 'in_progress'". If it does not match, ok:false.
+ *
+ * Not taking expected_version is asymmetric with claimTask but intentional: claim needs version to
+ * detect the conflict where "multiple unassigned agents read the same open task and someone snatched
+ * it before claim". block/resume/handoff are transitions on a task whose assignee is already fixed to
+ * a single subject, and only that assignee is eligible. The only real conflict leaving blocked
+ * (concurrent resume ⇄ handoff) is serialized by the status condition + handoff's BEGIN IMMEDIATE,
+ * functioning as "status itself is the CAS" (leaving blocked happens only once). resume has no
+ * "freshness at read time" dependency like claim, so ABA is not harmful either.
+ */
+export declare function blockTask(cdb: CoordDb, taskId: string, agentId: string): {
+    ok: boolean;
+};
+/**
+ * §4.x resume_task — same-agent resume when a human says "continue" (blocked → in_progress).
+ *
+ * Since blockTask keeps the claim, the same logical agent can return it with an assignee match. The
+ * worktree stays as-is. heartbeat_at is updated to now to revive the lease (afterward it returns to
+ * being under sweep supervision as a normal in_progress). Handing to another worker is done not by
+ * resume but by handoff (only when a human says so explicitly).
+ *
+ * CAS: conditioned on "assignee = agentId and status = 'blocked'". If it does not match, ok:false
+ * (held by another agent / already in_progress/open, etc.).
+ *
+ * Like blockTask, it does not take expected_version (intentional; see blockTask's doc for the
+ * reason). Even if resume ⇄ handoff run concurrently, the status='blocked' in both WHERE clauses lets
+ * only one win first and the other gets changes==0, so it is serialized without needing version.
+ */
+export declare function resumeTask(cdb: CoordDb, taskId: string, agentId: string): {
+    ok: boolean;
+};
+export type HandoffResult = {
+    ok: true;
+    /** Counts of the accompanying state that was moved (for the caller's confirmation/logs). */
+    moved: {
+        worktrees: number;
+        claims: number;
+        dirty_sets: number;
+    };
+    /** The list of worktree paths after the move (where the new agent cd's to). */
+    worktrees: string[];
+} | {
+    ok: false;
+    reason: 'not_found' | 'conflict';
+    current?: Pick<Task, 'assignee' | 'status' | 'version'>;
+};
+/**
+ * §4.7 handoff — **move a blocked task to another worker per worktree, all at once** (briefing D-3 decided).
+ *
+ * Adopted operation: resuming from suspension is, in principle, resume_task (same agent). Handing to
+ * another worker is **only when a human says so explicitly**, and this handoff is the sole path. So
+ * when this function is called, a human decision has already been made (the gate is outside the MCP
+ * tool = on the orchestrator/human side).
+ *
+ * "Per-worktree bulk move" means reassigning the following that the stuck agent A held to agent B, all
+ * in the **same CAS transaction**:
+ *   1. the task itself      : blocked(assignee=A) → in_progress(assignee=B), heartbeat revived
+ *   2. worktree_assignments : this task's active worktree from agent A → B (branch/path unchanged = physical side as-is)
+ *   3. claims (glob lease)  : active claims with task_id=this task and holder=A to holder B
+ *   4. dirty_sets           : the (agent_id=A) rows of the moved worktree to agent_id=B
+ * This way B inherits "the worktree A physically created, the claims it held, and the published dirty
+ * set" wholesale and can continue from where the predecessor's work surface left off (the process
+ * cannot be switched over, but the work can).
+ *
+ * Preventing double handoff: BEGIN IMMEDIATE + a CAS of "assignee=fromAgent and status='blocked'".
+ * If it was already moved to another agent / resumed / is held by someone other than A, changes==0 →
+ * conflict and nothing moves. No new exclusion mechanism is added (follows the existing CAS style).
+ *
+ * worktree_path/branch are not changed: the physical worktree stays as-is on the FS, and only the
+ * owner (agent_id) is reassigned. B cd's into this worktree path and continues. As a measure for
+ * dirty_sets' UNIQUE(agent_id, worktree_path), in case B previously left a dirty row for the same
+ * worktree, DELETE B's leftover for the same worktree in the same transaction before the UPDATE
+ * (since a history of A↔B going back and forth over the same deterministic worktree via §4.5
+ * reconnection could make (B, path) duplicate).
+ *
+ * Limiting the entry condition to blocked is intentional: being able to snatch-move an in_progress
+ * task would be a "steal work from a live worker" accident. A move always follows the order "suspend
+ * (blocked), then a human names another worker".
+ */
+export declare function handoffTask(cdb: CoordDb, args: {
+    taskId: string;
+    fromAgent: string;
+    toAgent: string;
+}): HandoffResult;
+/**
+ * Set a task to done (called from the merge gate on a successful merge).
+ * The same CAS style as claimTask: conditioned on "assignee = agentId and status = 'in_progress'",
+ * update status='done', version+1, and updated_at.
+ *
+ * The only legitimate basis for the done transition is the fact of "merged into the main line", so
+ * this function is called only at merge.ts's merge-success point (follows the role separation from
+ * release_task = return-to-open only). If it does not match, ok:false (held by another agent /
+ * already done/open, etc.).
+ */
+export declare function completeTask(cdb: CoordDb, taskId: string, agentId: string): {
+    ok: boolean;
+};
+/**
+ * §4.x list_tasks(status='blocked') — orphan visualization of blocked tasks.
+ *
+ * blocked is excluded from the lease sweep = kept indefinitely, so a "worker stuck and the human
+ * forgot too" orphan can arise. This is **picked up by visualization rather than auto-reclamation**
+ * (the adopted operation policy). No new table is added; it is provided as a join view over existing
+ * data (tasks.updated_at/assignee + agents.last_seen_at + board_messages).
+ *
+ * Derived values attached to each row:
+ * - blocked_age_sec   = now - tasks.updated_at   (elapsed since it dropped to blocked; older = longer neglected)
+ * - agent_silent_sec  = now - agents.last_seen_at (the holder's silence time; null if agent unknown)
+ * - last_question     = the latest question body with this task as ref_task_id (the stuck reason; null if none)
+ *
+ * The threshold (how many seconds counts as an orphan) is not hardcoded; the caller/operation decides
+ * by looking at blocked_age_sec and agent_silent_sec.
+ *
+ * Order: the default is updated_at ascending (longest neglected first). list_tasks(status='blocked')
+ * calls it with order='priority' to align with the same priority order as other statuses (a caller
+ * wanting longest-neglected-first sorts by blocked_age_sec).
+ */
+export interface BlockedTaskView extends Task {
+    blocked_age_sec: number;
+    agent_silent_sec: number | null;
+    last_question: string | null;
+}
+export declare function listBlockedTasks(cdb: CoordDb, args?: {
+    repo?: string;
+    assignee?: string;
+    ticketId?: string;
+    now?: number;
+    order?: 'oldest_first' | 'priority';
+}): BlockedTaskView[];
+/**
+ * §4.2 lease sweep — reclaim expired claims + return heartbeat-lapsed tasks to open.
+ * Assumed to run piggybacked at the head of each tool call rather than a resident cron.
+ */
+export declare function sweepExpired(cdb: CoordDb, now?: number): void;
+export interface HeartbeatOpts {
+    /** Also update the held task's heartbeat_at (a claiming worker specifies its own task). */
+    taskId?: string;
+    /**
+     * Whether to update agents.last_seen_at to now (default true).
+     *
+     * Set to false for tools where "someone who is not the worker process itself operates the ledger"
+     * (block_task / resume_task / handoff_task). These are invoked by the orchestrator/human, so
+     * freshening agents.last_seen with that operation time would pollute a blocked task's
+     * agent_silent_sec (= the metric for the worker process's liveness) with the "operation time" and
+     * skew orphan detection. So, to not confuse "operation time" with "worker liveness time", do not
+     * touch the agent's last_seen for operations by non-owners. The claims lease extension is also tied
+     * to the owner's liveness, so suppress it likewise.
+     */
+    touchAgent?: boolean;
+    /**
+     * Whether to update the heartbeat_at of all in_progress tasks assigned to this agent to now
+     * (default equals touchAgent = true only on the owner's liveness signal).
+     *
+     * Issue #51 handling. Previously heartbeat() updated tasks.heartbeat_at only when opts.taskId was
+     * explicit. But the piggyback call at the head of each tool handler passes heartbeat(cdb, agentId)
+     * without taskId, so agents.last_seen and the claims lease extended but only the task lease did
+     * not; if after claiming you kept calling only publish_dirty etc. at intervals under
+     * TASK_LEASE_SEC without calling the heartbeat tool, the sweepExpired running at the head of
+     * another agent's tool call would return the task to open — an accident. So, to make the
+     * description "heartbeat is piggybacked onto every tool call" (proposal 4) match actual behavior,
+     * add a path that extends the lease of owned in_progress tasks even on a piggyback that passes no taskId.
+     *
+     * For operations invoked by non-owners (block_task / resume_task / handoff_task = touchAgent:false),
+     * the task lease must not be freshened (so as not to pollute blocked tasks' orphan decision). So the
+     * default is aligned to touchAgent, and if touchAgent=false, touchOwnedTasks is automatically
+     * treated as false (the simplest policy to link the owner-liveness-tied behaviors together).
+     * blocked tasks are kept indefinitely and excluded from the lease sweep, so they are intentionally
+     * excluded (not touched).
+     */
+    touchOwnedTasks?: boolean;
+}
+/**
+ * The heartbeat piggybacked onto every tool call. Updates the worker's own liveness time
+ * (agents.last_seen) and the lease of held tasks/claims.
+ *
+ * The 3rd argument also accepts a taskId string for backward compatibility (= same as { taskId }).
+ * Passing touchAgent=false suppresses the extension of agents.last_seen and the claims lease
+ * (for operations invoked by non-owners = the orchestrator/human; prevents polluting orphan detection).
+ *
+ * Issue #51 handling: even on a piggyback call that passes no taskId (heartbeat(cdb, agentId)), if
+ * touchOwnedTasks (default = touchAgent) is true, extend the heartbeat_at of all in_progress tasks
+ * assigned to that agent to now. This way the task lease is maintained by the piggyback of each tool
+ * call alone, even without calling the heartbeat tool (with taskId), and prevents wrongful
+ * reclamation by sweepExpired.
+ */
+export declare function heartbeat(cdb: CoordDb, agentId: string, opts?: string | HeartbeatOpts): void;