@cleocode/core 2026.9.23 → 2026.9.25

package/dist/task-work/claims.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Caller-side claim operations: who is claiming, and the lease lifecycle
+ * verbs built on the accessor's claim chokepoint (T12502 · epic T12497).
+ *
+ * The compare-and-set itself lives in the store (`updateTaskFields` with a
+ * `TaskClaimGuard`, reached through `DataAccessor.claimTask` /
+ * `unclaimTask`). This module resolves the CALLER's identity — its bound
+ * session (never the newest-active guess, T12500) and agent id — and maps the
+ * CLI flags to a claim mode.
+ *
+ * @task T12502
+ * @epic T12497
+ */
+import type { TaskClaim, TaskClaimMode } from '@cleocode/contracts';
+import type { DataAccessor } from '../store/data-accessor.js';
+/** The identity a claim is recorded under. */
+export interface Claimant {
+    /** The caller's bound session, or `null` when unbound (no lease is taken). */
+    sessionId: string | null;
+    /** The caller's agent identity, or `null`. */
+    agentId: string | null;
+}
+/** Explicit overrides for a claim that another session holds. */
+export interface ClaimOverrideFlags {
+    /** Take over a lease that has EXPIRED (`--take-over`). Audited. */
+    takeOver?: boolean;
+    /** Take over even a LIVE lease (`--force-claim`). Audited. */
+    forceClaim?: boolean;
+}
+/**
+ * Resolve the claimant for the calling process.
+ *
+ * The session is the caller's BOUND session (connection, `CLEO_SESSION_ID`
+ * naming a real row, or the terminal binding) — an unbound caller claims as
+ * `null` and holds no lease. The agent id is the explicit one, else the bound
+ * session's agent identity, else `CLEO_AGENT_ID`.
+ *
+ * @param cwd - Project root for session resolution.
+ * @param agentId - Explicit agent id (`cleo claim --agent`), when given.
+ * @returns The claimant.
+ * @example
+ * ```ts
+ * const claimant = await resolveClaimant(projectRoot);
+ * ```
+ */
+export declare function resolveClaimant(cwd?: string, agentId?: string | null): Promise<Claimant>;
+/**
+ * Map override flags to a claim mode.
+ *
+ * @param flags - `--take-over` / `--force-claim`.
+ * @returns `force`, `take-over` or `acquire`.
+ * @example
+ * ```ts
+ * claimModeFor({ takeOver: true }); // 'take-over'
+ * ```
+ */
+export declare function claimModeFor(flags: ClaimOverrideFlags): Exclude<TaskClaimMode, 'release'>;
+/**
+ * Release `taskId`'s lease when `sessionId` holds it; a no-op otherwise
+ * (unclaimed, or held by another session — never an error).
+ *
+ * @param acc - Task accessor (may be inside a transaction).
+ * @param taskId - The task.
+ * @param sessionId - The caller's session.
+ * @returns `true` when a lease was released.
+ * @example
+ * ```ts
+ * await releaseOwnClaim(acc, 'T1', claimant.sessionId);
+ * ```
+ */
+export declare function releaseOwnClaim(acc: DataAccessor, taskId: string, sessionId: string | null): Promise<boolean>;
+/**
+ * Heartbeat: extend every lease the session holds by one lease length.
+ *
+ * @param acc - Task accessor.
+ * @param sessionId - The holder session.
+ * @param now - Clock override (ISO-8601 UTC) for tests.
+ * @returns Number of leases renewed.
+ * @example
+ * ```ts
+ * await renewClaimsForSession(acc, req.sessionId);
+ * ```
+ */
+export declare function renewClaimsForSession(acc: DataAccessor, sessionId: string, now?: string): Promise<number>;
+/**
+ * Activity heartbeat for a project (T12502): extend every lease `sessionId`
+ * holds there. The CLI dispatcher calls it after each successful mutation by
+ * a bound session, so an agent that keeps working keeps its claims.
+ *
+ * @param projectRoot - Project root.
+ * @param sessionId - The session that just did work.
+ * @returns Number of leases renewed.
+ * @example
+ * ```ts
+ * await renewProjectSessionClaims(projectRoot, req.sessionId);
+ * ```
+ */
+export declare function renewProjectSessionClaims(projectRoot: string, sessionId: string): Promise<number>;
+/** What one session heartbeat did (T12540). */
+export interface SessionHeartbeatResult {
+    /** `true` when the session's `lastActivity` was written (not throttled or skipped). */
+    readonly activityTouched: boolean;
+    /** Claim leases extended. */
+    readonly leasesRenewed: number;
+}
+/**
+ * The ONE activity heartbeat a bound session's successful mutation triggers
+ * (T12540 · T12502): refresh the session's `lastActivity` (throttled to once
+ * per `SESSION_ACTIVITY_THROTTLE_MS`) and extend its claim leases. Both halves
+ * are best-effort, cheap in the common case (an indexed read, no write lock),
+ * and skip rather than wait on a contended lock; a failure of one never stops
+ * the other.
+ *
+ * @param projectRoot - Project root.
+ * @param sessionId - The session that just did work.
+ * @param nowMs - Clock override for tests.
+ * @returns What the beat did.
+ * @example
+ * ```ts
+ * await heartbeatProjectSession(projectRoot, req.sessionId);
+ * ```
+ * @task T12540
+ */
+export declare function heartbeatProjectSession(projectRoot: string, sessionId: string, nowMs?: number): Promise<SessionHeartbeatResult>;
+/**
+ * The sessions among `sessionIds` that hold a LIVE claim lease (T12502). A
+ * lease is renewed by every mutation its holder makes (the dispatch
+ * heartbeat), so a live lease proves the session did work within one lease
+ * length — `session gc` uses this to keep a long-running session that is
+ * still working from being orphaned (which would drop its leases).
+ *
+ * @param projectRoot - Project root.
+ * @param sessionIds - Candidate sessions.
+ * @param now - ISO-8601 UTC instant for the expiry comparison.
+ * @returns The subset holding at least one unexpired lease.
+ * @example
+ * ```ts
+ * const alive = await sessionsHoldingLiveClaims(root, ['ses_a', 'ses_b']);
+ * ```
+ */
+export declare function sessionsHoldingLiveClaims(projectRoot: string, sessionIds: readonly string[], now?: string): Promise<Set<string>>;
+/**
+ * Renew one task's lease for its holder (`cleo claim <id> --renew`).
+ *
+ * @param acc - Task accessor.
+ * @param taskId - The task.
+ * @param claimant - The caller; must be the holder.
+ * @returns The renewed lease.
+ * @throws CleoError `E_TASK_CLAIMED` when another session holds it, or
+ *   `E_NOT_FOUND` when the caller holds no lease on it.
+ * @example
+ * ```ts
+ * await renewTaskClaim(acc, 'T1', claimant);
+ * ```
+ */
+export declare function renewTaskClaim(acc: DataAccessor, taskId: string, claimant: Claimant): Promise<TaskClaim | null>;
+/**
+ * What {@link claimSpawnedTask} changed, so a failed spawn can undo it with
+ * {@link releaseSpawnClaim} (T12502).
+ */
+export interface SpawnClaimReceipt {
+    /** The lease the spawned session now holds, or `null` when the task does not exist. */
+    readonly claim: TaskClaim | null;
+    /** The lease on the task before the spawn (e.g. the orchestrator's), if any. */
+    readonly previous: TaskClaim | null;
+}
+/**
+ * Claim a task for the agent a spawn is about to start (T12502).
+ *
+ * The spawned agent's own session takes the lease and records the calling
+ * orchestrator session as its spawn-edge parent (`parentSessionId`) and as
+ * the trusted spawner (`spawnedBySessionId`, via `setSessionSpawnedBy` —
+ * the only edge the claim chokepoint honours). When the
+ * orchestrator's session held the lease (it ran `cleo start` or `cleo claim`
+ * first), the lease is handed to the spawned session (audited as a
+ * hand-off). Parent and child are one claim family: either may take the lease
+ * back without an override, so a worker whose calls resolve to the
+ * orchestrator's session is not refused by its own spawn. Any other live or
+ * expired holder refuses the spawn with `E_TASK_CLAIMED`. A re-spawn reuses
+ * the same per-agent session, so it renews its own lease. A task that does
+ * not exist is left to the spawn's own validation.
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task being spawned.
+ * @param identity - The spawned agent's session and agent id.
+ * @returns The lease taken and the lease it replaced (for rollback).
+ * @throws CleoError `E_TASK_CLAIMED` when another session holds the task.
+ * @example
+ * ```ts
+ * const receipt = await claimSpawnedTask(root, 'T1', { sessionId: s.sessionId, agentId: s.agentId });
+ * ```
+ */
+export declare function claimSpawnedTask(projectRoot: string, taskId: string, identity: {
+    sessionId: string;
+    agentId: string | null;
+}): Promise<SpawnClaimReceipt>;
+/**
+ * Undo {@link claimSpawnedTask} for a spawn that failed after claiming
+ * (T12502): release the spawned session's lease and give the task back to
+ * the session that held it before (the orchestrator on a hand-off). A lease
+ * the spawned session already held before this spawn (a re-spawn) is kept.
+ * Best-effort: a failure here never masks the spawn's own error.
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task whose spawn failed.
+ * @param sessionId - The spawned session.
+ * @param receipt - What the claim changed.
+ * @returns `true` when the spawn's lease was undone.
+ * @example
+ * ```ts
+ * if (!spawnSucceeded) await releaseSpawnClaim(root, taskId, child.sessionId, receipt);
+ * ```
+ */
+export declare function releaseSpawnClaim(projectRoot: string, taskId: string, sessionId: string, receipt: SpawnClaimReceipt): Promise<boolean>;
+//# sourceMappingURL=claims.d.ts.map

package/dist/task-work/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/task-work/claims.ts"],"names":[],"mappings":"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"}

package/dist/task-work/claims.js

@@ -0,0 +1,272 @@
+/**
+ * Caller-side claim operations: who is claiming, and the lease lifecycle
+ * verbs built on the accessor's claim chokepoint (T12502 · epic T12497).
+ *
+ * The compare-and-set itself lives in the store (`updateTaskFields` with a
+ * `TaskClaimGuard`, reached through `DataAccessor.claimTask` /
+ * `unclaimTask`). This module resolves the CALLER's identity — its bound
+ * session (never the newest-active guess, T12500) and agent id — and maps the
+ * CLI flags to a claim mode.
+ *
+ * @task T12502
+ * @epic T12497
+ */
+import { and, gt, inArray } from 'drizzle-orm';
+import { getTaskAccessor } from '../store/data-accessor.js';
+import { getSession, resolveBoundSession, setSessionSpawnedBy, touchSessionActivity, updateSession, } from '../store/session-store.js';
+import { getDb } from '../store/sqlite.js';
+import { leaseExpiresAtFrom, taskClaimLeaseMs } from '../store/task-claim.js';
+import * as schema from '../store/tasks-schema.js';
+/**
+ * Resolve the claimant for the calling process.
+ *
+ * The session is the caller's BOUND session (connection, `CLEO_SESSION_ID`
+ * naming a real row, or the terminal binding) — an unbound caller claims as
+ * `null` and holds no lease. The agent id is the explicit one, else the bound
+ * session's agent identity, else `CLEO_AGENT_ID`.
+ *
+ * @param cwd - Project root for session resolution.
+ * @param agentId - Explicit agent id (`cleo claim --agent`), when given.
+ * @returns The claimant.
+ * @example
+ * ```ts
+ * const claimant = await resolveClaimant(projectRoot);
+ * ```
+ */
+export async function resolveClaimant(cwd, agentId) {
+    const bound = await resolveBoundSession(cwd);
+    const session = bound?.session;
+    return {
+        sessionId: session?.id ?? null,
+        agentId: agentId ||
+            session?.agentIdentifier ||
+            session?.agentHandle ||
+            process.env['CLEO_AGENT_ID'] ||
+            null,
+    };
+}
+/**
+ * Map override flags to a claim mode.
+ *
+ * @param flags - `--take-over` / `--force-claim`.
+ * @returns `force`, `take-over` or `acquire`.
+ * @example
+ * ```ts
+ * claimModeFor({ takeOver: true }); // 'take-over'
+ * ```
+ */
+export function claimModeFor(flags) {
+    if (flags.forceClaim)
+        return 'force';
+    if (flags.takeOver)
+        return 'take-over';
+    return 'acquire';
+}
+/**
+ * Release `taskId`'s lease when `sessionId` holds it; a no-op otherwise
+ * (unclaimed, or held by another session — never an error).
+ *
+ * @param acc - Task accessor (may be inside a transaction).
+ * @param taskId - The task.
+ * @param sessionId - The caller's session.
+ * @returns `true` when a lease was released.
+ * @example
+ * ```ts
+ * await releaseOwnClaim(acc, 'T1', claimant.sessionId);
+ * ```
+ */
+export async function releaseOwnClaim(acc, taskId, sessionId) {
+    if (!sessionId)
+        return false;
+    const task = await acc.loadSingleTask(taskId);
+    if (task?.claim?.sessionId !== sessionId)
+        return false;
+    return acc.unclaimTask(taskId, { sessionId });
+}
+/**
+ * Heartbeat: extend every lease the session holds by one lease length.
+ *
+ * @param acc - Task accessor.
+ * @param sessionId - The holder session.
+ * @param now - Clock override (ISO-8601 UTC) for tests.
+ * @returns Number of leases renewed.
+ * @example
+ * ```ts
+ * await renewClaimsForSession(acc, req.sessionId);
+ * ```
+ */
+export async function renewClaimsForSession(acc, sessionId, now = new Date().toISOString()) {
+    return acc.renewSessionClaims(sessionId, leaseExpiresAtFrom(now, taskClaimLeaseMs()));
+}
+/**
+ * Activity heartbeat for a project (T12502): extend every lease `sessionId`
+ * holds there. The CLI dispatcher calls it after each successful mutation by
+ * a bound session, so an agent that keeps working keeps its claims.
+ *
+ * @param projectRoot - Project root.
+ * @param sessionId - The session that just did work.
+ * @returns Number of leases renewed.
+ * @example
+ * ```ts
+ * await renewProjectSessionClaims(projectRoot, req.sessionId);
+ * ```
+ */
+export async function renewProjectSessionClaims(projectRoot, sessionId) {
+    return renewClaimsForSession(await getTaskAccessor(projectRoot), sessionId);
+}
+/**
+ * The ONE activity heartbeat a bound session's successful mutation triggers
+ * (T12540 · T12502): refresh the session's `lastActivity` (throttled to once
+ * per `SESSION_ACTIVITY_THROTTLE_MS`) and extend its claim leases. Both halves
+ * are best-effort, cheap in the common case (an indexed read, no write lock),
+ * and skip rather than wait on a contended lock; a failure of one never stops
+ * the other.
+ *
+ * @param projectRoot - Project root.
+ * @param sessionId - The session that just did work.
+ * @param nowMs - Clock override for tests.
+ * @returns What the beat did.
+ * @example
+ * ```ts
+ * await heartbeatProjectSession(projectRoot, req.sessionId);
+ * ```
+ * @task T12540
+ */
+export async function heartbeatProjectSession(projectRoot, sessionId, nowMs = Date.now()) {
+    const activityTouched = await touchSessionActivity(sessionId, projectRoot, nowMs).catch(() => false);
+    const leasesRenewed = await renewClaimsForSession(await getTaskAccessor(projectRoot), sessionId, new Date(nowMs).toISOString());
+    return { activityTouched, leasesRenewed };
+}
+/**
+ * The sessions among `sessionIds` that hold a LIVE claim lease (T12502). A
+ * lease is renewed by every mutation its holder makes (the dispatch
+ * heartbeat), so a live lease proves the session did work within one lease
+ * length — `session gc` uses this to keep a long-running session that is
+ * still working from being orphaned (which would drop its leases).
+ *
+ * @param projectRoot - Project root.
+ * @param sessionIds - Candidate sessions.
+ * @param now - ISO-8601 UTC instant for the expiry comparison.
+ * @returns The subset holding at least one unexpired lease.
+ * @example
+ * ```ts
+ * const alive = await sessionsHoldingLiveClaims(root, ['ses_a', 'ses_b']);
+ * ```
+ */
+export async function sessionsHoldingLiveClaims(projectRoot, sessionIds, now = new Date().toISOString()) {
+    if (sessionIds.length === 0)
+        return new Set();
+    const db = await getDb(projectRoot);
+    const rows = await db
+        .selectDistinct({ sessionId: schema.tasks.claimedBySession })
+        .from(schema.tasks)
+        .where(and(inArray(schema.tasks.claimedBySession, [...sessionIds]), gt(schema.tasks.leaseExpiresAt, now)))
+        .all();
+    return new Set(rows.flatMap((r) => (r.sessionId ? [r.sessionId] : [])));
+}
+/**
+ * Renew one task's lease for its holder (`cleo claim <id> --renew`).
+ *
+ * @param acc - Task accessor.
+ * @param taskId - The task.
+ * @param claimant - The caller; must be the holder.
+ * @returns The renewed lease.
+ * @throws CleoError `E_TASK_CLAIMED` when another session holds it, or
+ *   `E_NOT_FOUND` when the caller holds no lease on it.
+ * @example
+ * ```ts
+ * await renewTaskClaim(acc, 'T1', claimant);
+ * ```
+ */
+export async function renewTaskClaim(acc, taskId, claimant) {
+    return acc.claimTask(taskId, { ...claimant, mode: 'renew' });
+}
+/**
+ * Claim a task for the agent a spawn is about to start (T12502).
+ *
+ * The spawned agent's own session takes the lease and records the calling
+ * orchestrator session as its spawn-edge parent (`parentSessionId`) and as
+ * the trusted spawner (`spawnedBySessionId`, via `setSessionSpawnedBy` —
+ * the only edge the claim chokepoint honours). When the
+ * orchestrator's session held the lease (it ran `cleo start` or `cleo claim`
+ * first), the lease is handed to the spawned session (audited as a
+ * hand-off). Parent and child are one claim family: either may take the lease
+ * back without an override, so a worker whose calls resolve to the
+ * orchestrator's session is not refused by its own spawn. Any other live or
+ * expired holder refuses the spawn with `E_TASK_CLAIMED`. A re-spawn reuses
+ * the same per-agent session, so it renews its own lease. A task that does
+ * not exist is left to the spawn's own validation.
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task being spawned.
+ * @param identity - The spawned agent's session and agent id.
+ * @returns The lease taken and the lease it replaced (for rollback).
+ * @throws CleoError `E_TASK_CLAIMED` when another session holds the task.
+ * @example
+ * ```ts
+ * const receipt = await claimSpawnedTask(root, 'T1', { sessionId: s.sessionId, agentId: s.agentId });
+ * ```
+ */
+export async function claimSpawnedTask(projectRoot, taskId, identity) {
+    const acc = await getTaskAccessor(projectRoot);
+    const task = await acc.loadSingleTask(taskId);
+    if (!task)
+        return { claim: null, previous: null };
+    const orchestrator = (await resolveBoundSession(projectRoot))?.session;
+    if (orchestrator && orchestrator.id !== identity.sessionId) {
+        const child = await getSession(identity.sessionId, projectRoot);
+        if (child && !child.parentSessionId) {
+            await updateSession(identity.sessionId, { parentSessionId: orchestrator.id }, projectRoot);
+        }
+        // The TRUSTED spawn edge: the claim chokepoint reads this, never the
+        // self-declared `parentSessionId`, to let the family share the lease.
+        if (child)
+            await setSessionSpawnedBy(identity.sessionId, orchestrator.id, projectRoot);
+    }
+    const claim = await acc.claimTask(taskId, {
+        sessionId: identity.sessionId,
+        agentId: identity.agentId,
+        mode: 'acquire',
+        handoffFrom: orchestrator?.id ?? null,
+    });
+    return { claim, previous: task.claim ?? null };
+}
+/**
+ * Undo {@link claimSpawnedTask} for a spawn that failed after claiming
+ * (T12502): release the spawned session's lease and give the task back to
+ * the session that held it before (the orchestrator on a hand-off). A lease
+ * the spawned session already held before this spawn (a re-spawn) is kept.
+ * Best-effort: a failure here never masks the spawn's own error.
+ *
+ * @param projectRoot - Project root.
+ * @param taskId - The task whose spawn failed.
+ * @param sessionId - The spawned session.
+ * @param receipt - What the claim changed.
+ * @returns `true` when the spawn's lease was undone.
+ * @example
+ * ```ts
+ * if (!spawnSucceeded) await releaseSpawnClaim(root, taskId, child.sessionId, receipt);
+ * ```
+ */
+export async function releaseSpawnClaim(projectRoot, taskId, sessionId, receipt) {
+    if (!receipt.claim || receipt.previous?.sessionId === sessionId)
+        return false;
+    try {
+        const acc = await getTaskAccessor(projectRoot);
+        if (!(await releaseOwnClaim(acc, taskId, sessionId)))
+            return false;
+        const previous = receipt.previous;
+        if (previous) {
+            await acc.claimTask(taskId, {
+                sessionId: previous.sessionId,
+                agentId: previous.agentId,
+                mode: 'acquire',
+            });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=claims.js.map

package/dist/task-work/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../../src/task-work/claims.ts"],"names":[],"mappings":"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"}

package/dist/task-work/index.d.ts

@@ -5,9 +5,12 @@
  * @epic T4454
  */
 import '../hooks/handlers/index.js';
-import type { KnowledgeCoverage } from '@cleocode/contracts';
+import type { KnowledgeCoverage, TaskClaim } from '@cleocode/contracts';
 import { type StaleFocusPointer } from '../sessions/focus-state-store.js';
 import type { DataAccessor } from '../store/data-accessor.js';
+import { type ClaimOverrideFlags } from './claims.js';
+export type { Claimant, ClaimOverrideFlags, SessionHeartbeatResult, SpawnClaimReceipt, } from './claims.js';
+export { claimModeFor, claimSpawnedTask, heartbeatProjectSession, releaseOwnClaim, releaseSpawnClaim, renewClaimsForSession, renewProjectSessionClaims, renewTaskClaim, resolveClaimant, } from './claims.js';
 /** Result of getting current task. */
 export interface TaskCurrentResult {
     currentTask: string | null;
@@ -27,7 +30,17 @@ export interface TaskStartResult {
     taskId: string;
     taskTitle: string;
     previousTask: string | null;
+    /**
+     * The claim lease this start holds on the task, or `null` when the caller
+     * is not bound to a session (no lease is taken). @task T12502
+     */
+    claim: TaskClaim | null;
 }
+/**
+ * Options for {@link startTask}: explicit, audited overrides of another
+ * session's claim (T12502).
+ */
+export type StartTaskOptions = ClaimOverrideFlags;
 /** Task work history entry. */
 export interface TaskWorkHistoryEntry {
     taskId: string;
@@ -39,16 +52,47 @@ export interface TaskWorkHistoryEntry {
  * @task T4750
  */
 export declare function currentTask(cwd?: string, accessor?: DataAccessor): Promise<TaskCurrentResult>;
+/**
+ * Refuse to start `taskId` while it has unresolved dependencies — the
+ * readiness check {@link startTask} runs before it takes any claim or writes
+ * focus. Exported so a composite verb (`pivot`) can run it BEFORE its own
+ * side effects instead of discovering the refusal half-way (T12502).
+ *
+ * @param acc - Task accessor.
+ * @param taskId - The task about to be started.
+ * @throws CleoError `DEPENDENCY_ERROR` naming the unresolved blockers.
+ * @example
+ * ```ts
+ * await assertTaskStartable(acc, 'T2');
+ * ```
+ * @task T12502
+ */
+export declare function assertTaskStartable(acc: DataAccessor, taskId: string): Promise<void>;
 /**
  * Start working on a specific task.
+ *
+ * T12502: the start takes the caller session's claim lease on the task with a
+ * compare-and-set inside the same write transaction as the focus write. When
+ * another session holds the task the start is refused with `E_TASK_CLAIMED`
+ * naming the holder and lease expiry; `takeOver` takes an expired lease and
+ * `forceClaim` a live one (both audited). The human `assignee` is not touched.
+ * Starting a new task releases the lease this session held on its previous one.
+ *
+ * @param taskId - Task to start.
+ * @param cwd - Project root.
+ * @param accessor - Task accessor (tests inject one).
+ * @param options - Claim overrides (`--take-over`, `--force-claim`).
  * @task T4462
  * @task T4750
+ * @task T12502
  */
-export declare function startTask(taskId: string, cwd?: string, accessor?: DataAccessor): Promise<TaskStartResult>;
+export declare function startTask(taskId: string, cwd?: string, accessor?: DataAccessor, options?: StartTaskOptions): Promise<TaskStartResult>;
 /**
- * Stop working on the current task.
+ * Stop working on the current task. T12502: releases the claim lease the
+ * caller's session holds on it (a lease held by another session is left).
  * @task T4462
  * @task T4750
+ * @task T12502
  */
 export declare function stopTask(cwd?: string, accessor?: DataAccessor): Promise<{
     previousTask: string | null;

package/dist/task-work/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/task-work/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,qBAAqB,CAAC;AAK5E,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAmC9D,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAiB5B;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,eAAe,CAAC,CA8E1B;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAuC1C;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAmBjC;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,uBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/task-work/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAiB,MAAM,qBAAqB,CAAC;AAKvF,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAK9D,OAAO,EACL,KAAK,kBAAkB,EAIxB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,QAAQ,EACR,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,eAAe,GAChB,MAAM,aAAa,CAAC;AAcrB,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAElD,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAiB5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,EACvB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAmF1B;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA4C1C;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAmBjC;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,uBAAiB,CAAC"}