@cleocode/core 2026.9.23 → 2026.9.25

package/dist/store/task-claim.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Leased agent claims on tasks — lease arithmetic and the typed refusal (T12502).
+ *
+ * A claim is four columns on `tasks_tasks` (`claimed_by_session`,
+ * `claimed_by_agent`, `claimed_at`, `lease_expires_at`), separate from the
+ * human `assignee`. It is written ONLY through the T12503 field chokepoint
+ * (`updateTaskFields`) with a `TaskClaimGuard`, which turns the claim into a
+ * compare-and-set in the UPDATE's WHERE clause (see
+ * `sqlite-data-accessor.ts#claimPredicate`). This module holds what the
+ * chokepoint and its callers share:
+ *
+ *  - the lease TTL ({@link taskClaimLeaseMs}) and expiry
+ *    ({@link leaseExpiresAtFrom});
+ *  - the row → {@link TaskClaim} mapping ({@link claimFromColumns});
+ *  - the `E_TASK_CLAIMED` error ({@link taskClaimedError}), which names the
+ *    holder, the lease expiry and the one explicit, audited override.
+ *
+ * Lifecycle: taken by `cleo start` / `cleo claim` / spawn; renewed by the
+ * holder session's mutations (dispatch heartbeat) or `cleo claim --renew`;
+ * released by `cleo stop`, `cleo unclaim`, and — via SQL triggers — by the
+ * task reaching done / cancelled / archived and by the holder session ending
+ * or being deleted. An expired lease is never taken silently: `--take-over`.
+ *
+ * @task T12502
+ * @epic T12497
+ */
+import { type TaskClaim, type TaskClaimMode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+/** Default claim lease: 30 minutes, renewed by the holder's activity. */
+export declare const DEFAULT_TASK_CLAIM_LEASE_MS: number;
+/**
+ * Environment override for the lease length, in whole minutes. Values that
+ * are not positive integers are ignored.
+ */
+export declare const TASK_CLAIM_LEASE_ENV = "CLEO_CLAIM_LEASE_MINUTES";
+/**
+ * Resolve the claim lease length in milliseconds.
+ *
+ * @returns `CLEO_CLAIM_LEASE_MINUTES` in ms when set to a positive integer,
+ *   else {@link DEFAULT_TASK_CLAIM_LEASE_MS}.
+ * @example
+ * ```ts
+ * const expires = leaseExpiresAtFrom(now, taskClaimLeaseMs());
+ * ```
+ */
+export declare function taskClaimLeaseMs(): number;
+/**
+ * Compute a lease expiry.
+ *
+ * @param now - ISO-8601 UTC instant the lease starts or is renewed.
+ * @param leaseMs - Lease length in milliseconds.
+ * @returns The ISO-8601 UTC expiry instant.
+ * @example
+ * ```ts
+ * leaseExpiresAtFrom('2026-09-29T00:00:00.000Z', 60_000); // '2026-09-29T00:01:00.000Z'
+ * ```
+ */
+export declare function leaseExpiresAtFrom(now: string, leaseMs: number): string;
+/** The claim columns as stored on a task row. */
+export interface TaskClaimColumns {
+    /** `claimed_by_session`. */
+    claimedBySession: string | null;
+    /** `claimed_by_agent`. */
+    claimedByAgent: string | null;
+    /** `claimed_at`. */
+    claimedAt: string | null;
+    /** `lease_expires_at`. */
+    leaseExpiresAt: string | null;
+}
+/**
+ * Map stored claim columns to a {@link TaskClaim}.
+ *
+ * @param row - The claim columns of a task row.
+ * @returns The lease, or `undefined` when the task is unclaimed.
+ * @example
+ * ```ts
+ * const claim = claimFromColumns(row); // undefined for an unclaimed task
+ * ```
+ */
+export declare function claimFromColumns(row: TaskClaimColumns): TaskClaim | undefined;
+/**
+ * The claim columns for a loaded task's lease (all `null` when unclaimed).
+ *
+ * @param claim - The lease on a task, if any.
+ * @returns The four claim columns.
+ * @example
+ * ```ts
+ * claimColumnsOf(task.claim).claimedBySession;
+ * ```
+ */
+export declare function claimColumnsOf(claim: TaskClaim | undefined): TaskClaimColumns;
+/**
+ * Whether a lease has lapsed at `now`. A lease with no recorded expiry
+ * counts as lapsed (it can never be renewed into validity by its holder
+ * anyway, and must not block forever).
+ *
+ * @param claim - The stored lease.
+ * @param now - ISO-8601 UTC instant to compare against.
+ * @returns `true` when `leaseExpiresAt <= now`.
+ * @example
+ * ```ts
+ * isClaimExpired(holder, new Date().toISOString());
+ * ```
+ */
+export declare function isClaimExpired(claim: TaskClaim, now: string): boolean;
+/**
+ * Whether a claim write in `mode` by `sessionId` may replace the stored lease.
+ * This is the JavaScript mirror of the SQL predicate; the chokepoint uses the
+ * SQL form for the write and this form only to explain a refusal.
+ *
+ * @param stored - The lease on the row, or `undefined` when unclaimed.
+ * @param mode - The claim mode.
+ * @param sessionId - The caller's session (`null` when unbound).
+ * @param now - ISO-8601 UTC instant for the expiry comparison.
+ * @param allowedHolders - Sessions whose lease `acquire` / `take-over` may take
+ *   even while live: the spawn hand-off source and the caller's spawn-edge
+ *   parent and children (`tasks_sessions.parent_session_id`).
+ * @returns `true` when the write is allowed.
+ * @example
+ * ```ts
+ * claimAllows(stored, 'acquire', 'ses_a', now); // false when ses_b holds it
+ * ```
+ */
+export declare function claimAllows(stored: TaskClaim | undefined, mode: TaskClaimMode, sessionId: string | null, now: string, allowedHolders?: readonly string[]): boolean;
+/**
+ * Build the `E_TASK_CLAIMED` refusal.
+ *
+ * @param taskId - The claimed task.
+ * @param holder - The lease stored on the task.
+ * @param requester - The refused caller.
+ * @param now - ISO-8601 UTC instant used for the expiry comparison.
+ * @param verb - The refused command, for the fix hint (`start`, `claim`, …).
+ * @returns A {@link CleoError} with `ExitCode.TASK_CLAIMED` (LAFS
+ *   `E_TASK_CLAIMED`) and {@link TaskClaimedDetails} as `details`.
+ * @example
+ * ```ts
+ * throw taskClaimedError('T1', holder, { sessionId: 'ses_b', agentId: null }, now);
+ * ```
+ */
+export declare function taskClaimedError(taskId: string, holder: TaskClaim, requester: {
+    sessionId: string | null;
+    agentId: string | null;
+}, now: string, verb?: string): CleoError;
+//# sourceMappingURL=task-claim.d.ts.map

package/dist/store/task-claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-claim.d.ts","sourceRoot":"","sources":["../../src/store/task-claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAOzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,0BAA0B;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oBAAoB;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0BAA0B;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAQ7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAO7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,GAAG,EAAE,MAAM,EACX,cAAc,GAAE,SAAS,MAAM,EAAO,GACrC,OAAO,CAST;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE;IAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC/D,GAAG,EAAE,MAAM,EACX,IAAI,SAAU,GACb,SAAS,CAwBX"}

package/dist/store/task-claim.js

@@ -0,0 +1,195 @@
+/**
+ * Leased agent claims on tasks — lease arithmetic and the typed refusal (T12502).
+ *
+ * A claim is four columns on `tasks_tasks` (`claimed_by_session`,
+ * `claimed_by_agent`, `claimed_at`, `lease_expires_at`), separate from the
+ * human `assignee`. It is written ONLY through the T12503 field chokepoint
+ * (`updateTaskFields`) with a `TaskClaimGuard`, which turns the claim into a
+ * compare-and-set in the UPDATE's WHERE clause (see
+ * `sqlite-data-accessor.ts#claimPredicate`). This module holds what the
+ * chokepoint and its callers share:
+ *
+ *  - the lease TTL ({@link taskClaimLeaseMs}) and expiry
+ *    ({@link leaseExpiresAtFrom});
+ *  - the row → {@link TaskClaim} mapping ({@link claimFromColumns});
+ *  - the `E_TASK_CLAIMED` error ({@link taskClaimedError}), which names the
+ *    holder, the lease expiry and the one explicit, audited override.
+ *
+ * Lifecycle: taken by `cleo start` / `cleo claim` / spawn; renewed by the
+ * holder session's mutations (dispatch heartbeat) or `cleo claim --renew`;
+ * released by `cleo stop`, `cleo unclaim`, and — via SQL triggers — by the
+ * task reaching done / cancelled / archived and by the holder session ending
+ * or being deleted. An expired lease is never taken silently: `--take-over`.
+ *
+ * @task T12502
+ * @epic T12497
+ */
+import { ExitCode, } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+/** Default claim lease: 30 minutes, renewed by the holder's activity. */
+export const DEFAULT_TASK_CLAIM_LEASE_MS = 30 * 60 * 1000;
+/**
+ * Environment override for the lease length, in whole minutes. Values that
+ * are not positive integers are ignored.
+ */
+export const TASK_CLAIM_LEASE_ENV = 'CLEO_CLAIM_LEASE_MINUTES';
+/**
+ * Resolve the claim lease length in milliseconds.
+ *
+ * @returns `CLEO_CLAIM_LEASE_MINUTES` in ms when set to a positive integer,
+ *   else {@link DEFAULT_TASK_CLAIM_LEASE_MS}.
+ * @example
+ * ```ts
+ * const expires = leaseExpiresAtFrom(now, taskClaimLeaseMs());
+ * ```
+ */
+export function taskClaimLeaseMs() {
+    const raw = process.env[TASK_CLAIM_LEASE_ENV];
+    if (raw && /^\d+$/.test(raw)) {
+        const minutes = Number(raw);
+        if (minutes > 0)
+            return minutes * 60 * 1000;
+    }
+    return DEFAULT_TASK_CLAIM_LEASE_MS;
+}
+/**
+ * Compute a lease expiry.
+ *
+ * @param now - ISO-8601 UTC instant the lease starts or is renewed.
+ * @param leaseMs - Lease length in milliseconds.
+ * @returns The ISO-8601 UTC expiry instant.
+ * @example
+ * ```ts
+ * leaseExpiresAtFrom('2026-09-29T00:00:00.000Z', 60_000); // '2026-09-29T00:01:00.000Z'
+ * ```
+ */
+export function leaseExpiresAtFrom(now, leaseMs) {
+    return new Date(Date.parse(now) + leaseMs).toISOString();
+}
+/**
+ * Map stored claim columns to a {@link TaskClaim}.
+ *
+ * @param row - The claim columns of a task row.
+ * @returns The lease, or `undefined` when the task is unclaimed.
+ * @example
+ * ```ts
+ * const claim = claimFromColumns(row); // undefined for an unclaimed task
+ * ```
+ */
+export function claimFromColumns(row) {
+    if (!row.claimedBySession)
+        return undefined;
+    return {
+        sessionId: row.claimedBySession,
+        agentId: row.claimedByAgent,
+        claimedAt: row.claimedAt ?? '',
+        leaseExpiresAt: row.leaseExpiresAt ?? '',
+    };
+}
+/**
+ * The claim columns for a loaded task's lease (all `null` when unclaimed).
+ *
+ * @param claim - The lease on a task, if any.
+ * @returns The four claim columns.
+ * @example
+ * ```ts
+ * claimColumnsOf(task.claim).claimedBySession;
+ * ```
+ */
+export function claimColumnsOf(claim) {
+    return {
+        claimedBySession: claim?.sessionId ?? null,
+        claimedByAgent: claim?.agentId ?? null,
+        claimedAt: claim?.claimedAt ?? null,
+        leaseExpiresAt: claim?.leaseExpiresAt ?? null,
+    };
+}
+/**
+ * Whether a lease has lapsed at `now`. A lease with no recorded expiry
+ * counts as lapsed (it can never be renewed into validity by its holder
+ * anyway, and must not block forever).
+ *
+ * @param claim - The stored lease.
+ * @param now - ISO-8601 UTC instant to compare against.
+ * @returns `true` when `leaseExpiresAt <= now`.
+ * @example
+ * ```ts
+ * isClaimExpired(holder, new Date().toISOString());
+ * ```
+ */
+export function isClaimExpired(claim, now) {
+    return claim.leaseExpiresAt === '' || claim.leaseExpiresAt <= now;
+}
+/**
+ * Whether a claim write in `mode` by `sessionId` may replace the stored lease.
+ * This is the JavaScript mirror of the SQL predicate; the chokepoint uses the
+ * SQL form for the write and this form only to explain a refusal.
+ *
+ * @param stored - The lease on the row, or `undefined` when unclaimed.
+ * @param mode - The claim mode.
+ * @param sessionId - The caller's session (`null` when unbound).
+ * @param now - ISO-8601 UTC instant for the expiry comparison.
+ * @param allowedHolders - Sessions whose lease `acquire` / `take-over` may take
+ *   even while live: the spawn hand-off source and the caller's spawn-edge
+ *   parent and children (`tasks_sessions.parent_session_id`).
+ * @returns `true` when the write is allowed.
+ * @example
+ * ```ts
+ * claimAllows(stored, 'acquire', 'ses_a', now); // false when ses_b holds it
+ * ```
+ */
+export function claimAllows(stored, mode, sessionId, now, allowedHolders = []) {
+    if (mode === 'force')
+        return true;
+    if (mode === 'renew' || mode === 'release') {
+        return stored !== undefined && sessionId !== null && stored.sessionId === sessionId;
+    }
+    if (!stored)
+        return true;
+    if (sessionId !== null && stored.sessionId === sessionId)
+        return true;
+    if (allowedHolders.includes(stored.sessionId))
+        return true;
+    return mode === 'take-over' && isClaimExpired(stored, now);
+}
+/**
+ * Build the `E_TASK_CLAIMED` refusal.
+ *
+ * @param taskId - The claimed task.
+ * @param holder - The lease stored on the task.
+ * @param requester - The refused caller.
+ * @param now - ISO-8601 UTC instant used for the expiry comparison.
+ * @param verb - The refused command, for the fix hint (`start`, `claim`, …).
+ * @returns A {@link CleoError} with `ExitCode.TASK_CLAIMED` (LAFS
+ *   `E_TASK_CLAIMED`) and {@link TaskClaimedDetails} as `details`.
+ * @example
+ * ```ts
+ * throw taskClaimedError('T1', holder, { sessionId: 'ses_b', agentId: null }, now);
+ * ```
+ */
+export function taskClaimedError(taskId, holder, requester, now, verb = 'start') {
+    const expired = isClaimExpired(holder, now);
+    const override = expired ? '--take-over' : '--force-claim';
+    const details = {
+        field: 'claimedBySession',
+        taskId,
+        holder,
+        expired,
+        requester,
+        override,
+    };
+    const who = holder.agentId
+        ? `session ${holder.sessionId} (agent ${holder.agentId})`
+        : `session ${holder.sessionId}`;
+    const lease = expired
+        ? `its lease expired at ${holder.leaseExpiresAt}`
+        : `lease expires ${holder.leaseExpiresAt}`;
+    const fix = expired
+        ? `The holder stopped renewing its lease. Take the task over explicitly (audited): cleo ${verb} ${taskId} --take-over`
+        : `Pick another task (cleo next), wait for the lease to expire at ${holder.leaseExpiresAt}, or override the live lease (audited): cleo ${verb} ${taskId} --force-claim`;
+    return new CleoError(ExitCode.TASK_CLAIMED, `Task ${taskId} is claimed by ${who}; ${lease}.`, {
+        fix,
+        details: { ...details },
+    });
+}
+//# sourceMappingURL=task-claim.js.map

package/dist/store/task-claim.js.map

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

package/dist/store/task-version.d.ts

@@ -11,7 +11,13 @@
  *     leave the row at a version a stale reader already holds (no ABA).
  *  2. The comparison ({@link assertTaskVersion}) runs after `BEGIN IMMEDIATE`
  *     holds the database write lock, so no other process can commit between
- *     the check and the write.
+ *     the check and the write. The field-level chokepoint
+ *     (`updateTaskFields`) additionally puts the version in the UPDATE's
+ *     WHERE clause, so a guarded write is a single compare-and-set statement.
+ *
+ * A conflict is raised by {@link taskConflictError}: `E_CONFLICT` with the
+ * current version, the fields that differ from the caller's read, the stored
+ * values to merge against, and a `--if-match` retry hint.
  *
  * `withWriteRetry` only absorbs `SQLITE_BUSY`; it cannot detect a lost update.
  * These helpers are what turn a stale read-modify-write into a typed
@@ -20,6 +26,8 @@
  * @task T12503
  * @epic T12497
  */
+import { type Task, type TaskConflictChange } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
 /** The minimal row shape that carries a task version. */
 export interface TaskVersionSource {
     /** Last-update timestamp (ISO 8601), or null/undefined for a never-updated row. */
@@ -51,6 +59,36 @@ export declare function taskVersion(row: TaskVersionSource | null | undefined):
  * ```
  */
 export declare function nextTaskVersion(current: TaskVersionSource | null | undefined, now?: string): string;
+/**
+ * List the fields whose stored value differs from the caller's read.
+ *
+ * The version field (`updatedAt`) is never listed; an absent field and an
+ * explicit `null` compare equal.
+ *
+ * @param baseline - The task as the caller read it.
+ * @param current - The task as stored now.
+ * @returns One entry per differing field, sorted by field name.
+ * @example
+ * ```ts
+ * diffTaskFields(before, after); // [{ field: 'labels', was: '["a"]', now: '["a","b"]' }]
+ * ```
+ */
+export declare function diffTaskFields(baseline: Task, current: Task): TaskConflictChange[];
+/**
+ * Build the `E_CONFLICT` error for a stale task write.
+ *
+ * @param taskId - Task being written.
+ * @param expectedUpdatedAt - The version the caller expected.
+ * @param current - The row as stored now; a full task adds the merge summary.
+ * @param baseline - The task as the caller read it, when the write path has it.
+ * @returns A {@link CleoError} with `ExitCode.VERSION_CONFLICT` (LAFS
+ *   `E_CONFLICT`), a fix hint, and {@link TaskConflictDetails} as `details`.
+ * @example
+ * ```ts
+ * throw taskConflictError('T1', expected, await accessor.loadSingleTask('T1'), baseline);
+ * ```
+ */
+export declare function taskConflictError(taskId: string, expectedUpdatedAt: string, current: Task | TaskVersionSource | null, baseline?: Task): CleoError;
 /**
  * Throw `E_CONFLICT` when the caller's expected version no longer matches.
  *
@@ -60,13 +98,13 @@ export declare function nextTaskVersion(current: TaskVersionSource | null | unde
  * @param taskId - Task being written.
  * @param current - The row as read inside the write transaction.
  * @param expectedUpdatedAt - The version the caller read, if it supplied one.
+ * @param baseline - The task as the caller read it; enables the changed-field summary.
  * @throws {CleoError} `ExitCode.VERSION_CONFLICT` (LAFS `E_CONFLICT`) with
- *   `details.expected` = the caller's version and `details.actual` = the
- *   current version.
+ *   {@link TaskConflictDetails} as `details`.
  * @example
  * ```ts
- * assertTaskVersion('T1', current, guard?.expectedUpdatedAt);
+ * assertTaskVersion('T1', current, guard?.expectedUpdatedAt, guard?.baseline);
  * ```
  */
-export declare function assertTaskVersion(taskId: string, current: TaskVersionSource, expectedUpdatedAt: string | undefined): void;
+export declare function assertTaskVersion(taskId: string, current: Task | TaskVersionSource, expectedUpdatedAt: string | undefined, baseline?: Task): void;
 //# sourceMappingURL=task-version.d.ts.map

package/dist/store/task-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-version.d.ts","sourceRoot":"","sources":["../../src/store/task-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC7C,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,EAC1B,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACpC,IAAI,CAiBN"}
+{"version":3,"file":"task-version.d.ts","sourceRoot":"","sources":["../../src/store/task-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC7C,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAOR;AA6BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,kBAAkB,EAAE,CAclF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,IAAI,GAAG,iBAAiB,GAAG,IAAI,EACxC,QAAQ,CAAC,EAAE,IAAI,GACd,SAAS,CAkCX;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,GAAG,iBAAiB,EACjC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,QAAQ,CAAC,EAAE,IAAI,GACd,IAAI,CAIN"}

package/dist/store/task-version.js

@@ -11,7 +11,13 @@
  *     leave the row at a version a stale reader already holds (no ABA).
  *  2. The comparison ({@link assertTaskVersion}) runs after `BEGIN IMMEDIATE`
  *     holds the database write lock, so no other process can commit between
- *     the check and the write.
+ *     the check and the write. The field-level chokepoint
+ *     (`updateTaskFields`) additionally puts the version in the UPDATE's
+ *     WHERE clause, so a guarded write is a single compare-and-set statement.
+ *
+ * A conflict is raised by {@link taskConflictError}: `E_CONFLICT` with the
+ * current version, the fields that differ from the caller's read, the stored
+ * values to merge against, and a `--if-match` retry hint.
  *
  * `withWriteRetry` only absorbs `SQLITE_BUSY`; it cannot detect a lost update.
  * These helpers are what turn a stale read-modify-write into a typed
@@ -20,7 +26,8 @@
  * @task T12503
  * @epic T12497
  */
-import { ExitCode } from '@cleocode/contracts';
+import { isDeepStrictEqual } from 'node:util';
+import { ExitCode, } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
 /**
  * Return the version of a task row: `updatedAt`, else `createdAt`, else `''`.
@@ -57,6 +64,104 @@ export function nextTaskVersion(current, now) {
         return candidate;
     return new Date(stored + 1).toISOString();
 }
+/** Longest JSON summary of one field value carried on a conflict error. */
+const CONFLICT_VALUE_MAX = 200;
+/** Most entries of `current.labels` / `current.depends` carried on a conflict error. */
+const CONFLICT_LIST_MAX = 50;
+/** Cut a string to {@link CONFLICT_VALUE_MAX} characters, marking the cut. */
+function truncate(text) {
+    return text.length <= CONFLICT_VALUE_MAX ? text : `${text.slice(0, CONFLICT_VALUE_MAX - 1)}…`;
+}
+/** Fields never reported as "changed": the version itself. */
+const CONFLICT_IGNORED_FIELDS = new Set(['updatedAt']);
+/** JSON of a field value for a conflict summary, truncated; `null` when absent. */
+function summarizeValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        return null;
+    return truncate(json);
+}
+/** Narrow a version source to a full task row. */
+function isFullTask(row) {
+    return 'id' in row && 'title' in row && 'status' in row;
+}
+/**
+ * List the fields whose stored value differs from the caller's read.
+ *
+ * The version field (`updatedAt`) is never listed; an absent field and an
+ * explicit `null` compare equal.
+ *
+ * @param baseline - The task as the caller read it.
+ * @param current - The task as stored now.
+ * @returns One entry per differing field, sorted by field name.
+ * @example
+ * ```ts
+ * diffTaskFields(before, after); // [{ field: 'labels', was: '["a"]', now: '["a","b"]' }]
+ * ```
+ */
+export function diffTaskFields(baseline, current) {
+    // Values are heterogeneous task fields that are only compared and JSON-encoded.
+    const was = new Map(Object.entries(baseline));
+    const now = new Map(Object.entries(current));
+    const fields = [...new Set([...was.keys(), ...now.keys()])].sort();
+    const changes = [];
+    for (const field of fields) {
+        if (CONFLICT_IGNORED_FIELDS.has(field))
+            continue;
+        const before = was.get(field) ?? null;
+        const after = now.get(field) ?? null;
+        if (isDeepStrictEqual(before, after))
+            continue;
+        changes.push({ field, was: summarizeValue(before), now: summarizeValue(after) });
+    }
+    return changes;
+}
+/**
+ * Build the `E_CONFLICT` error for a stale task write.
+ *
+ * @param taskId - Task being written.
+ * @param expectedUpdatedAt - The version the caller expected.
+ * @param current - The row as stored now; a full task adds the merge summary.
+ * @param baseline - The task as the caller read it, when the write path has it.
+ * @returns A {@link CleoError} with `ExitCode.VERSION_CONFLICT` (LAFS
+ *   `E_CONFLICT`), a fix hint, and {@link TaskConflictDetails} as `details`.
+ * @example
+ * ```ts
+ * throw taskConflictError('T1', expected, await accessor.loadSingleTask('T1'), baseline);
+ * ```
+ */
+export function taskConflictError(taskId, expectedUpdatedAt, current, baseline) {
+    const currentVersion = taskVersion(current);
+    const full = current !== null && isFullTask(current) ? current : null;
+    const changes = full && baseline ? diffTaskFields(baseline, full) : [];
+    const details = {
+        field: 'updatedAt',
+        expected: expectedUpdatedAt,
+        actual: currentVersion,
+        currentVersion,
+        changedFields: changes.map((change) => change.field),
+        changes,
+        current: full
+            ? {
+                title: truncate(full.title),
+                status: full.status,
+                priority: full.priority,
+                labels: (full.labels ?? []).slice(0, CONFLICT_LIST_MAX),
+                labelsTotal: full.labels?.length ?? 0,
+                depends: (full.depends ?? []).slice(0, CONFLICT_LIST_MAX),
+                dependsTotal: full.depends?.length ?? 0,
+                parentId: full.parentId ?? null,
+            }
+            : null,
+    };
+    const changed = details.changedFields.length > 0 ? ` Changed: ${details.changedFields.join(', ')}.` : '';
+    return new CleoError(ExitCode.VERSION_CONFLICT, `Task ${taskId} changed since it was read (expected version ${expectedUpdatedAt}, current ${currentVersion}).${changed}`, {
+        fix: `Re-read the task (cleo show ${taskId}), merge your change onto it, then retry with --if-match ${currentVersion}`,
+        details: { ...details },
+    });
+}
 /**
  * Throw `E_CONFLICT` when the caller's expected version no longer matches.
  *
@@ -66,28 +171,19 @@ export function nextTaskVersion(current, now) {
  * @param taskId - Task being written.
  * @param current - The row as read inside the write transaction.
  * @param expectedUpdatedAt - The version the caller read, if it supplied one.
+ * @param baseline - The task as the caller read it; enables the changed-field summary.
  * @throws {CleoError} `ExitCode.VERSION_CONFLICT` (LAFS `E_CONFLICT`) with
- *   `details.expected` = the caller's version and `details.actual` = the
- *   current version.
+ *   {@link TaskConflictDetails} as `details`.
  * @example
  * ```ts
- * assertTaskVersion('T1', current, guard?.expectedUpdatedAt);
+ * assertTaskVersion('T1', current, guard?.expectedUpdatedAt, guard?.baseline);
  * ```
  */
-export function assertTaskVersion(taskId, current, expectedUpdatedAt) {
+export function assertTaskVersion(taskId, current, expectedUpdatedAt, baseline) {
     if (expectedUpdatedAt === undefined)
         return;
-    const currentVersion = taskVersion(current);
-    if (currentVersion === expectedUpdatedAt)
+    if (taskVersion(current) === expectedUpdatedAt)
         return;
-    throw new CleoError(ExitCode.VERSION_CONFLICT, `Task ${taskId} changed since it was read (expected version ${expectedUpdatedAt}, current ${currentVersion})`, {
-        fix: `Re-read the task (cleo show ${taskId}) and retry with --expected-updated-at ${currentVersion}`,
-        details: {
-            field: 'updatedAt',
-            expected: expectedUpdatedAt,
-            actual: currentVersion,
-            currentVersion,
-        },
-    });
+    throw taskConflictError(taskId, expectedUpdatedAt, current, baseline);
 }
 //# sourceMappingURL=task-version.js.map

package/dist/store/task-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"task-version.js","sourceRoot":"","sources":["../../src/store/task-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAUzC;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,GAAyC;IACnE,OAAO,GAAG,EAAE,SAAS,IAAI,GAAG,EAAE,SAAS,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA6C,EAC7C,GAAY;IAEZ,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,MAAM;QAAE,OAAO,SAAS,CAAC;IAC3D,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,OAA0B,EAC1B,iBAAqC;IAErC,IAAI,iBAAiB,KAAK,SAAS;QAAE,OAAO;IAC5C,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,cAAc,KAAK,iBAAiB;QAAE,OAAO;IACjD,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,gBAAgB,EACzB,QAAQ,MAAM,gDAAgD,iBAAiB,aAAa,cAAc,GAAG,EAC7G;QACE,GAAG,EAAE,+BAA+B,MAAM,0CAA0C,cAAc,EAAE;QACpG,OAAO,EAAE;YACP,KAAK,EAAE,WAAW;YAClB,QAAQ,EAAE,iBAAiB;YAC3B,MAAM,EAAE,cAAc;YACtB,cAAc;SACf;KACF,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"task-version.js","sourceRoot":"","sources":["../../src/store/task-version.ts"],"names":[],"mappings":"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"}

package/dist/store/tasks-schema.d.ts

@@ -17,6 +17,8 @@ export { AGENT_INSTANCE_STATUSES, AGENT_TYPES, agentErrorLog, agentInstances, }
 export type { NewWarpChainInstanceRow, NewWarpChainRow, WarpChainInstanceRow, WarpChainRow, } from './schema/chain-schema.js';
 export { warpChainInstances, warpChains } from './schema/chain-schema.js';
 export { tasksSchemaMeta as schemaMeta } from './schema/cleo-project/audit.js';
+export type { DocsAttachmentRefRow as AttachmentRefRow, DocsAttachmentRow as AttachmentRow, NewDocsAttachmentRefRow as NewAttachmentRefRow, NewDocsAttachmentRow as NewAttachmentRow, } from './schema/cleo-project/docs.js';
+export { docsAttachmentRefs as attachmentRefs, docsAttachments as attachments, } from './schema/cleo-project/docs.js';
 export type { NewTasksLifecycleEvidenceRow as NewLifecycleEvidenceRow, NewTasksLifecycleGateResultRow as NewLifecycleGateResultRow, NewTasksLifecyclePipelineRow as NewLifecyclePipelineRow, NewTasksLifecycleStageRow as NewLifecycleStageRow, NewTasksLifecycleTransitionRow as NewLifecycleTransitionRow, TasksLifecycleEvidenceRow as LifecycleEvidenceRow, TasksLifecycleGateResultRow as LifecycleGateResultRow, TasksLifecyclePipelineRow as LifecyclePipelineRow, TasksLifecycleStageRow as LifecycleStageRow, TasksLifecycleTransitionRow as LifecycleTransitionRow, } from './schema/cleo-project/lifecycle.js';
 export { tasksLifecycleEvidence as lifecycleEvidence, tasksLifecycleGateResults as lifecycleGateResults, tasksLifecyclePipelines as lifecyclePipelines, tasksLifecycleStages as lifecycleStages, tasksLifecycleTransitions as lifecycleTransitions, } from './schema/cleo-project/lifecycle.js';
 export { tasksCommitFiles as commitFiles, tasksCommits as commits, tasksTaskCommits as taskCommits, } from './schema/cleo-project/provenance-commits.js';

package/dist/store/tasks-schema.d.ts.map

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

package/dist/store/tasks-schema.js

@@ -29,6 +29,7 @@ export { warpChainInstances, warpChains } from './schema/chain-schema.js';
 // twin (key-aware, atomic) at every open, before any read: the initial
 // collapse, then whatever an older build wrote to the bare table since.
 export { tasksSchemaMeta as schemaMeta } from './schema/cleo-project/audit.js';
+export { docsAttachmentRefs as attachmentRefs, docsAttachments as attachments, } from './schema/cleo-project/docs.js';
 // COMPLETE-CUTOVER (T12017 · gh#1107) — lifecycle domain → PREFIXED tables.
 //
 // Completes the satellite-rebind deferred at the top of this file. The bare