@cleocode/contracts 2026.9.20 → 2026.9.22

package/src/operations/tasks.ts

@@ -1569,6 +1569,12 @@ export interface TasksUpdateQueryParams {
   addRelates?: Array<{ taskId: string; type: string; reason?: string }>;
   /** Remove related tasks by taskId. @task T9327 */
   removeRelates?: string[];
+  /**
+   * Optimistic-concurrency guard: the task `updatedAt` the caller read. When
+   * the stored version differs, the update fails with `E_CONFLICT` and the
+   * current version, instead of overwriting a newer write. @task T12503
+   */
+  expectedUpdatedAt?: string;
 }
 /**
  * Result of `tasks.update` — the updated task record with change list.
@@ -2602,6 +2608,7 @@ export const TASKS_UPDATE_INPUT_SCHEMA: JsonSchema = {
       },
     },
     removeRelates: { type: 'array', items: { type: 'string' } },
+    expectedUpdatedAt: { type: 'string', minLength: 1 },
   },
 };
 

package/src/operations/validate.ts

@@ -223,6 +223,11 @@ export interface ValidateGateParams {
    * `CLEO_STRICT_EVIDENCE=1`).
    */
   sharedEvidence?: boolean;
+  /**
+   * `--no-run` (T12621): serve typed gates from the result cache and execute
+   * none; a gate without a fresh cached pass refuses with `E_GATE_NOT_CACHED`.
+   */
+  noRun?: boolean;
 }
 export interface ValidateGateResult {
   taskId: string;

package/src/operations/worktree.ts

@@ -28,7 +28,7 @@
  * @task T1161
  */
 export interface WorktreeHook {
-  /** Shell command to run (executed via `sh -c` in the worktree dir). */
+  /** Shell command to run in the worktree dir (`/bin/sh -c` on POSIX, cmd.exe on Windows). */
   command: string;
   /**
    * When to run the hook.
@@ -97,6 +97,107 @@ export interface WorktreeIncludePattern {
   negated: boolean;
 }
 
+// ---------------------------------------------------------------------------
+// Per-task worktree lock (T12506)
+// ---------------------------------------------------------------------------
+
+/**
+ * Identity of the process that holds (or asks for) a task's worktree lock.
+ *
+ * Every field is optional on input: `createWorktree` fills `pid` and
+ * `processStartedAt` from the calling process when the caller does not name a
+ * longer-lived owner process. The spawn pipeline passes the per-agent session
+ * id, agent id, stable device id and the nearest non-launcher ancestor process
+ * (the harness that outlives the short `cleo` invocation).
+ *
+ * @task T12506
+ */
+export interface WorktreeLockHolder {
+  /** CLEO session id of the holder (`CLEO_SESSION_ID`). */
+  sessionId?: string | null;
+  /** Agent id of the holder (`CLEO_AGENT_ID`). */
+  agentId?: string | null;
+  /** Stable device id (`getStableDeviceId()`); pids are only comparable on one device. */
+  deviceId?: string | null;
+  /** Owner process id whose liveness keeps the lock held. */
+  pid?: number;
+  /**
+   * Owner process start time as rendered by `ps -o lstart=` under
+   * `PS_STABLE_ENV` (UTC, C locale). A live pid with a different start time is
+   * a recycled pid, i.e. the holder is dead.
+   */
+  processStartedAt?: string | null;
+}
+
+/**
+ * On-disk record of a held per-task worktree lock
+ * (`<cleoHome>/locks/worktrees/<projectHash>/<taskId>.lock`).
+ *
+ * Published atomically (write temp file, then hard-link into place, which
+ * fails with `EEXIST` when another holder won), so a reader never sees a
+ * partially written record.
+ *
+ * @task T12506
+ */
+export interface WorktreeLockRecord {
+  /** Record schema version. */
+  schemaVersion: 1;
+  /** Random token identifying this acquisition. */
+  token: string;
+  /** Task the lock guards. */
+  taskId: string;
+  /** Project hash scoping the worktree. */
+  projectHash: string;
+  /** Holder session id, or `null` when unknown. */
+  sessionId: string | null;
+  /** Holder agent id, or `null` when unknown. */
+  agentId: string | null;
+  /** Holder device id, or `null` when unknown. */
+  deviceId: string | null;
+  /** Holder owner process id. */
+  pid: number;
+  /** Holder owner process start time (`ps lstart`, UTC), or `null` when unprobeable. */
+  processStartedAt: string | null;
+  /** Host name of the holder. */
+  hostname: string;
+  /** ISO 8601 time the lock was acquired. */
+  acquiredAt: string;
+  /** ISO 8601 time of the holder's latest heartbeat. */
+  heartbeatAt: string;
+}
+
+/**
+ * How `createWorktree` obtained the per-task lock.
+ *
+ * - `acquired`: no lock existed.
+ * - `reclaimed`: a lock existed but its holder was provably dead (pid gone or
+ *   start time differs) or its heartbeat was older than the TTL.
+ * - `reentered`: the lock is held by the SAME caller (session id, agent id,
+ *   owner pid and start time all match), e.g. an orchestrator retrying its own
+ *   spawn; the existing worktree is re-attached.
+ *
+ * @task T12506
+ */
+export type WorktreeLockAcquisitionStatus = 'acquired' | 'reclaimed' | 'reentered';
+
+/**
+ * Lock outcome reported on {@link CreateWorktreeResult.lock}.
+ *
+ * @task T12506
+ */
+export interface WorktreeLockAcquisition {
+  /** How the lock was obtained. */
+  status: WorktreeLockAcquisitionStatus;
+  /** Absolute path of the lock file. */
+  lockPath: string;
+  /** The record now on disk. */
+  record: WorktreeLockRecord;
+  /** The previous holder's record when the lock was reclaimed. */
+  reclaimedFrom?: WorktreeLockRecord;
+  /** Why the previous holder was judged dead (`reclaimed` only). */
+  reclaimReason?: 'pid-gone' | 'pid-recycled' | 'heartbeat-stale' | 'unreadable';
+}
+
 // ---------------------------------------------------------------------------
 // Create operation
 // ---------------------------------------------------------------------------
@@ -178,6 +279,20 @@ export interface CreateWorktreeOptions {
    * @task T9807
    */
   spawnScope?: string;
+  /**
+   * Identity recorded in the per-task worktree lock (T12506). Missing fields
+   * default to the calling process (pid + `ps` start time).
+   *
+   * @task T12506
+   */
+  holder?: WorktreeLockHolder;
+  /**
+   * Heartbeat age (ms) beyond which an existing lock is reclaimable even when
+   * its owner pid is alive. Defaults to `CLEO_WORKTREE_LOCK_TTL_MS` or 4 hours.
+   *
+   * @task T12506
+   */
+  lockTtlMs?: number;
 }
 
 /**
@@ -211,8 +326,15 @@ export interface CreateWorktreeResult {
    * branch behind; false on a clean first-time creation.
    *
    * @task T1878
+   * @task T12506 — also true when an existing worktree directory was
+   *   re-attached instead of recreated (never force-removed).
    */
   reused: boolean;
+  /**
+   * Per-task lock acquired before `git worktree add` (T12506). Absent only on
+   * results synthesised by callers that skip provisioning (e.g. `--resume`).
+   */
+  lock?: WorktreeLockAcquisition;
   /** Environment variables to inject into the spawned agent process. */
   envVars: Record<string, string>;
   /** Prompt preamble text for agent isolation context. */
@@ -258,6 +380,16 @@ export interface DestroyWorktreeOptions {
    * @default true
    */
   deleteBranch?: boolean;
+  /**
+   * When true, `deleteBranch` also deletes a branch that carries commits on
+   * neither `origin/main` nor the project's current `HEAD`. Without it such a
+   * branch is kept and `error` explains why (T12506: unmerged agent work is
+   * never deleted implicitly).
+   *
+   * @default false
+   * @task T12506
+   */
+  forceDeleteUnmergedBranch?: boolean;
   /**
    * When true, force destruction even if the worktree has uncommitted changes.
    *

package/src/process-probe.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared constants for probing the OS process table with `ps`.
+ *
+ * @module process-probe
+ * @task T12500
+ * @task T12506
+ */
+
+/**
+ * Environment overrides for every `ps` probe (T12500): UTC and the C locale make
+ * the `lstart` start time independent of the caller's `TZ` / `LANG`. The
+ * terminal-identity ppid-chain keys (core) and the per-task worktree lock
+ * holder identity (`@cleocode/worktree`, T12506) both compare `lstart` strings
+ * written by one process and read by another, so both must render them the
+ * same way.
+ */
+export const PS_STABLE_ENV: Readonly<Record<'TZ' | 'LC_ALL' | 'LANG', string>> = {
+  TZ: 'UTC',
+  LC_ALL: 'C',
+  LANG: 'C',
+};

package/src/project-context.ts

@@ -70,14 +70,48 @@ export interface ProjectEvidenceContext {
    * `commit:` atom whose SHA exists in exactly one sibling, without help.
    */
   gitRoot?: string;
+  /**
+   * Accept required CI green on a merged PR's merge commit as `testsPassed` /
+   * `qaPassed` evidence (`ci:<pr>` atom, owner decision D11149). Only `true`
+   * enables it.
+   *
+   * @task T12634
+   */
+  ciSatisfies?: boolean;
+  /**
+   * Which required checks attest each gate for `ci:<pr>`. Each list must be a
+   * subset of the required-check list; a gate without a list refuses `ci:`.
+   *
+   * @task T12634
+   */
+  ciChecks?: {
+    tests?: string[];
+    qa?: string[];
+    /** Job-name globs that must have run and succeeded for a code task's gate. */
+    jobs?: { tests?: string[]; qa?: string[] };
+  };
+}
+
+/**
+ * A required check named in `release.prRequiredWorkflows`, optionally pinned to
+ * the GitHub App that must post it and (for a workflow) its workflow file, so a
+ * same-named check from another app never counts (T12634).
+ */
+export interface RequiredCheckPin {
+  /** Check-run (job) or workflow name. */
+  name: string;
+  /** GitHub App slug (e.g. `github-actions`) or numeric app id. */
+  app?: string | number;
+  /** Workflow file path (e.g. `.github/workflows/ci.yml`). */
+  workflow?: string;
 }
 
 /** Release and evidence behavior configured per project. */
 export interface ProjectReleaseContext {
   /** Branches whose reachable commits may satisfy `commit:` evidence atoms. */
   integrationBranches?: string[];
-  /** Required successful checks for `pr:` evidence atoms. */
-  prRequiredWorkflows?: string[];
+  /** Required successful checks for `pr:` / `ci:` evidence atoms; an entry may pin its app/workflow. */
+  prRequiredWorkflows?: Array<string | RequiredCheckPin>;
 }
 
 /** Schema-compliant project context for LLM agent consumption. */
@@ -90,6 +124,12 @@ export interface ProjectContext {
   testing?: {
     framework?: TestFramework;
     command?: string;
+    /**
+     * Affected-scope test command template for `tool:test-affected` (D11150,
+     * T12635): `{projects}`, `{filters}` and `{packages}` expand per affected
+     * package, e.g. `pnpm exec vitest run {projects}`.
+     */
+    affectedCommand?: string;
     testFilePatterns?: string[];
     directories?: {
       unit?: string;

package/src/project-lifecycle.ts

@@ -0,0 +1,149 @@
+/**
+ * Project relocation contracts — `cleo project move` and `cleo project reroot`
+ * (T12552 · T12558).
+ *
+ * Both relocations RENAME; nothing is copied, so the live database, its WAL
+ * sidecars and `.git` move atomically and there is never a second copy to
+ * diverge from the first.
+ *
+ * - `move` renames the whole project root to a new path on the SAME device.
+ *   A cross-device target is refused (`E_CROSS_DEVICE`).
+ * - `reroot` renames `.cleo/` (and CLEO's own top-level files) into a child
+ *   directory of the current root and leaves a {@link ProjectMovedTombstone}.
+ *
+ * Both support a dry run that returns a {@link ProjectRelocationPlan} and
+ * touches neither the disk nor the registry.
+ *
+ * @task T12552
+ * @task T12558
+ */
+
+/** Which relocation a plan or result describes. */
+export type ProjectRelocationKind = 'move' | 'reroot';
+
+/** The registry change a relocation makes. */
+export interface ProjectRelocationRegistryAction {
+  /**
+   * `rebind` points the project's registry row at the target (registering the
+   * project first when it has no row). Always explicit — never inferred.
+   */
+  action: 'rebind';
+  /** Location that becomes `live`. */
+  livePath: string;
+  /** Location demoted to `missing` — it no longer holds the project. */
+  demotedPath: string;
+  /** Always `missing`: after a rename the old location holds no store. */
+  demotedState: 'missing';
+  /** Always `carried`: the checkout nonce moves with the renamed `.cleo/`. */
+  nonce: 'carried';
+}
+
+/** A top-level entry a relocation leaves behind, and why. */
+export interface ProjectRelocationExclusion {
+  /** Entry name, relative to the source root. */
+  entry: string;
+  /** Why it is not moved. */
+  reason: string;
+}
+
+/**
+ * What a relocation WOULD do, returned by a dry run. Producing it writes
+ * nothing to disk and opens no database.
+ */
+export interface ProjectRelocationPlan {
+  /** Discriminant: always `true` for a plan. */
+  dryRun: true;
+  /** Which relocation. */
+  kind: ProjectRelocationKind;
+  /** Stable project id — preserved by every relocation. */
+  projectId: string;
+  /** Current absolute project root. */
+  source: string;
+  /** Absolute project root after the relocation. */
+  target: string;
+  /** Always `rename`: relocations never copy. */
+  transfer: 'rename';
+  /**
+   * Entries renamed, relative to `source`. `move` renames the root itself
+   * (`['.']`); `reroot` lists each top-level entry it moves into `target`.
+   */
+  entries: string[];
+  /** Top-level entries left behind, with the reason (reroot only). */
+  excluded: ProjectRelocationExclusion[];
+  /** Absolute paths of files the relocation writes. */
+  writes: string[];
+  /** The registry change. */
+  registry: ProjectRelocationRegistryAction;
+  /** Where the required pre-change checkpoint is written. */
+  checkpoint: string;
+  /**
+   * Conditions that make the real run refuse (`E_CROSS_DEVICE`, CLEO or git
+   * worktrees). Empty when none were found.
+   */
+  blockers: string[];
+  /** Checks only the real run performs (they would open a database). */
+  deferredChecks: string[];
+}
+
+/** Result of a completed `cleo project move`. */
+export interface MoveProjectResult {
+  /** Discriminant: always `false` for a completed move. */
+  dryRun: false;
+  /** Stable project id — unchanged. */
+  projectId: string;
+  /** The old absolute project root (no longer exists). */
+  oldPath: string;
+  /** The new absolute project root. */
+  newPath: string;
+  /** Id of the checkpoint taken before the rename. */
+  checkpointId: string;
+  /** Directory holding the checkpoint, outside the moved tree. */
+  checkpointPath: string;
+  /** Registry status after the rebind. */
+  reconcileStatus: 'ok' | 'path_updated' | 'auto_registered' | 'candidate';
+}
+
+/** Result of a completed (or resumed) `cleo project reroot`. */
+export interface RerootProjectResult {
+  /** Discriminant: always `false` for a completed reroot. */
+  dryRun: false;
+  /** Stable project id — unchanged. */
+  projectId: string;
+  /** Previous absolute project root (now holds only the tombstone). */
+  oldRoot: string;
+  /** New absolute project root (the child directory). */
+  newRoot: string;
+  /**
+   * `true` when this run finished a reroot an earlier run left half done
+   * (`.cleo/` already in the child, registry still on the old root).
+   */
+  resumed: boolean;
+  /** Id of the checkpoint taken before any change (empty on a resume). */
+  checkpointId: string;
+  /** Directory holding the checkpoint, outside the moved tree (empty on a resume). */
+  checkpointPath: string;
+  /** Top-level entries renamed from the old root into the new one. */
+  renamed: string[];
+  /** Whether `.cleo/project-id` was already present or had to be written. */
+  projectIdFile: 'present' | 'written';
+  /** Absolute path of the tombstone left at the old root. */
+  tombstone: string;
+  /** Registry status after the rebind. */
+  reconcileStatus: 'ok' | 'path_updated' | 'auto_registered' | 'candidate';
+  /** Follow-up the operator must do by hand (git bookkeeping). */
+  notes: string[];
+}
+
+/**
+ * `<oldRoot>/.cleo-moved.json` — left by `cleo project reroot` so a command
+ * run at the old root refuses with `E_PROJECT_MOVED` instead of silently
+ * creating an empty store there.
+ */
+export interface ProjectMovedTombstone {
+  /** The project that used to live here. */
+  projectId: string;
+  /** Absolute path of its new root. */
+  movedTo: string;
+  /** ISO 8601 timestamp of the relocation. */
+  at: string;
+}

package/src/release/plan.test.ts

@@ -187,7 +187,12 @@ describe('Release plan constant tuples', () => {
   });
 
   it('exports resolved-source attribution per ADR-061', () => {
-    expect(RESOLVED_SOURCE).toEqual(['project-context', 'language-default', 'legacy-alias']);
+    expect(RESOLVED_SOURCE).toEqual([
+      'project-context',
+      'package-script',
+      'language-default',
+      'legacy-alias',
+    ]);
   });
 
   it('exposes a stable schema version + URL', () => {

package/src/release/plan.ts

@@ -137,9 +137,15 @@ export const TASK_KIND = [
 export const IMPACT = ['major', 'minor', 'patch'] as const;
 
 /**
- * Source attribution for resolved tool commands. Mirrors ADR-061 §1 surfaces.
+ * Source attribution for resolved tool commands. Mirrors ADR-061 §1 surfaces;
+ * `package-script` is a project `package.json` script (T12633).
  */
-export const RESOLVED_SOURCE = ['project-context', 'language-default', 'legacy-alias'] as const;
+export const RESOLVED_SOURCE = [
+  'project-context',
+  'package-script',
+  'language-default',
+  'legacy-alias',
+] as const;
 
 // ─── Enum schemas ────────────────────────────────────────────────────────────