@cleocode/contracts 2026.9.19 → 2026.9.21

package/src/operations/nexus.ts

@@ -647,6 +647,12 @@ export interface NexusPermissionSetResult {
 export interface NexusReconcileParams {
   /** Override project root (defaults to cwd). */
   projectRoot?: string;
+  /**
+   * Rebind the registry row to this checkout even though its previous location
+   * still exists on this device (T12470). Without it such a checkout is only
+   * recorded as a `candidate` — a second checkout or a clone is not a move.
+   */
+  forceRebind?: boolean;
 }
 /** Result of `nexus.reconcile`. */
 export interface NexusReconcileResult {
@@ -1282,6 +1288,180 @@ export interface NexusProjectsListResult {
   projects: NexusProjectRecord[];
   /** Count of projects returned. */
   count: number;
+  /**
+   * Every device known to the global store (`nexus_devices`, T12510), most
+   * recent heartbeat first. A location's `deviceId` resolves against this list.
+   */
+  devices: NexusDeviceRecord[];
+}
+
+/**
+ * One machine that runs CLEO against the global store (`nexus_devices`, T12510).
+ * `deviceId` is the persisted `<cleoHome>/device-id` UUID that
+ * {@link NexusProjectCheckout.deviceId} carries.
+ */
+export interface NexusDeviceRecord {
+  /** Stable device id (`<cleoHome>/device-id`). */
+  deviceId: string;
+  /** Hostname at the last heartbeat. */
+  hostname: string;
+  /** Operating system (`process.platform`, e.g. `darwin`, `linux`, `win32`). */
+  os: string;
+  /** CPU architecture (`process.arch`, e.g. `arm64`, `x64`). */
+  arch: string;
+  /** CLEO version that sent the last heartbeat. */
+  cleoVersion: string;
+  /** ISO 8601 timestamp of the first heartbeat. */
+  firstSeen: string;
+  /** ISO 8601 timestamp of the most recent heartbeat. */
+  lastHeartbeatAt: string;
+  /** `true` for the device running this command. */
+  current: boolean;
+}
+
+/**
+ * One registry row a project NAME matched when the name is not unique
+ * (T12510). Carried in the `E_NEXUS_PROJECT_AMBIGUOUS` error's
+ * `details.candidates`; select one by its `projectId`.
+ */
+export interface NexusProjectCandidate {
+  /** Immutable project id — pass this instead of the name. */
+  projectId: string;
+  /** Registered project name (shared by every candidate). */
+  name: string;
+  /** Most recently encountered checkout path. */
+  path: string;
+  /** ISO 8601 timestamp the project was last seen. */
+  lastSeen: string;
+}
+
+/**
+ * Why a git state probe could not describe (all of) a location (T12511).
+ *
+ * - `E_PATH_MISSING` — the location's directory does not exist.
+ * - `E_PATH_ACCESS` — the directory exists but cannot be read (EACCES/EPERM).
+ * - `E_NOT_GIT_REPO` — neither the directory nor its declared
+ *   `evidence.gitRoot` is inside a git work tree.
+ * - `E_GIT_TIMEOUT` — git did not finish inside the per-row budget (a lock,
+ *   a credential prompt, a slow filesystem); its process group was killed.
+ * - `E_GIT_FAILED` — git exited non-zero for another reason.
+ * - `E_FETCH_FAILED` — `--fetch` was requested and the fetch failed; the local
+ *   fields are still filled and remote fields describe the PREVIOUS fetch.
+ */
+export type NexusGitProbeErrorCode =
+  | 'E_PATH_MISSING'
+  | 'E_PATH_ACCESS'
+  | 'E_NOT_GIT_REPO'
+  | 'E_GIT_TIMEOUT'
+  | 'E_GIT_FAILED'
+  | 'E_FETCH_FAILED';
+
+/**
+ * Git state of one project location on one device (`nexus_project_git_state`,
+ * T12511). Keyed like its location: `(projectId, deviceId, path)`.
+ *
+ * Remote fields (`ahead`, `behind`, `remoteHeadSha`) describe the remote as of
+ * the LAST FETCH, never now: the probe does not touch the network unless asked.
+ * `remoteFetchedAt` is that fetch's instant and `remoteStale` says whether it
+ * is older than the staleness window (or unknown), so a `behind: 0` is never
+ * read as "up to date" on the strength of a fetch from last month.
+ */
+export interface NexusProjectGitState {
+  /** Immutable project id. */
+  projectId: string;
+  /** Registered project name, when the registry row is present. */
+  projectName: string | null;
+  /** Stable id of the device the location is on. */
+  deviceId: string;
+  /** `true` when `deviceId` is the device running this command. */
+  current: boolean;
+  /** Location path (the checkout root CLEO recorded). */
+  path: string;
+  /** Directory git actually ran in: `path`, or its declared `evidence.gitRoot`. */
+  gitRoot: string | null;
+  /** Checked-out branch; `null` when detached or unknown. */
+  branch: string | null;
+  /** HEAD commit; `null` for an unborn branch or when the probe failed. */
+  headSha: string | null;
+  /** `true` when HEAD is detached. */
+  detached: boolean;
+  /** `true` for a shallow clone (ahead/behind may be truncated by the graft). */
+  shallow: boolean;
+  /** Tracked entries with staged or unstaged changes (incl. conflicts). */
+  dirtyCount: number | null;
+  /** Untracked, not-ignored entries. */
+  untrackedCount: number | null;
+  /** Upstream ref (e.g. `origin/main`); `null` when none is configured. */
+  upstream: string | null;
+  /** Commits on HEAD not on the upstream, as of the last fetch. */
+  ahead: number | null;
+  /** Commits on the upstream not on HEAD, as of the last fetch. */
+  behind: number | null;
+  /** Remote the upstream belongs to, else `origin`, else the first remote. */
+  remoteName: string | null;
+  /** That remote's configured URL. */
+  remoteUrl: string | null;
+  /** Upstream tracking-ref commit, as of the last fetch. */
+  remoteHeadSha: string | null;
+  /** ISO 8601 instant of the last fetch (FETCH_HEAD mtime); `null` if never. */
+  remoteFetchedAt: string | null;
+  /** `true` when `remoteFetchedAt` is unknown or older than the staleness window. */
+  remoteStale: boolean;
+  /** ISO 8601 instant this probe ran. */
+  probedAt: string;
+  /** Wall time of the probe, milliseconds. */
+  durationMs: number;
+  /** Why the probe could not describe (all of) the location; `null` on success. */
+  probeErrorCode: NexusGitProbeErrorCode | null;
+  /** Human-readable detail for `probeErrorCode` (git's stderr, the errno, …). */
+  probeError: string | null;
+}
+
+/** Parameters for `nexus.projects.status` (T12511). */
+export interface NexusProjectsStatusParams {
+  /** Run `git fetch` per location first (network). Default `false`. */
+  fetch?: boolean;
+  /** Locations probed at once. Default 8, clamped to 1..64. */
+  concurrency?: number;
+  /** Per-location budget for every git call it makes, ms. Default 10000 (30000 with fetch). */
+  timeoutMs?: number;
+  /** A fetch older than this is `remoteStale`, ms. Default 24h. */
+  staleAfterMs?: number;
+}
+
+/** Result of `nexus.projects.status` (T12511). */
+export interface NexusProjectsStatusResult {
+  /** Fresh probes of this device's live and missing locations. */
+  rows: NexusProjectGitState[];
+  /** Last recorded state of locations on OTHER devices (not re-probed). */
+  otherDevices: NexusProjectGitState[];
+  /** Number of fresh rows. */
+  count: number;
+  /** Device the probe ran on. */
+  deviceId: string;
+  /** Whether a fetch was attempted. */
+  fetched: boolean;
+  /** Effective concurrency. */
+  concurrency: number;
+  /** Effective per-location timeout, ms. */
+  timeoutMs: number;
+  /** Effective staleness window, ms. */
+  staleAfterMs: number;
+  /** Wall time of the whole probe, ms. */
+  durationMs: number;
+  /** Aggregate counts over `rows`. */
+  summary: {
+    /** Rows with no probe error. */
+    ok: number;
+    /** Rows with a probe error. */
+    errored: number;
+    /** Rows that timed out. */
+    timedOut: number;
+    /** Rows with at least one dirty or untracked entry. */
+    dirty: number;
+    /** Rows whose remote state is stale. */
+    remoteStale: number;
+  };
 }
 
 /** Parameters for `nexus.projects.register`. */
@@ -1363,9 +1543,16 @@ export interface NexusProjectsCleanParams {
   vacuum?: boolean;
 }
 
-/** One checkout of a project recorded in the device-local path map (T12354). */
+/**
+ * Lifecycle state of one project location in `nexus_project_locations` (T12469).
+ * `candidate` (T12470): the checkout declares the id but was never confirmed —
+ * it holds no registry binding and no permissions until promoted explicitly.
+ */
+export type NexusProjectLocationState = 'live' | 'missing' | 'superseded' | 'candidate';
+
+/** One recorded location (checkout) of a project on a device (T12354 · T12469). */
 export interface NexusProjectCheckout {
-  /** Absolute checkout root on this device. */
+  /** Absolute checkout root on the device named by `deviceId`. */
   projectPath: string;
   /** Path fingerprint of the checkout. */
   projectHash: string;
@@ -1373,8 +1560,12 @@ export interface NexusProjectCheckout {
   firstSeen: string;
   /** ISO 8601 timestamp the checkout was last encountered. */
   lastSeen: string;
-  /** Whether the checkout directory exists now. */
+  /** Whether the checkout directory exists now (always `false` for another device). */
   exists: boolean;
+  /** Stable id of the device the checkout is on (T12469). */
+  deviceId: string;
+  /** Location state: `live`, `missing` (directory gone) or `superseded` (T12469). */
+  state: NexusProjectLocationState;
 }
 
 /** Why a registry row matched `nexus.projects.clean` criteria (T12324). */
@@ -1464,6 +1655,227 @@ export interface NexusProjectsCleanResult {
   matchedByReason: Partial<Record<NexusProjectsCleanReason, number>>;
   /** Receipt of the applied removal; absent on dry-run or when nothing matched (T12324). */
   receipt?: NexusProjectsCleanReceipt;
+  /**
+   * Matched rows that were NOT removed because their id was found at another
+   * path (T12471): the project moved, it is not an orphan. Absent when none.
+   */
+  relocated?: NexusProjectsCleanRelocated[];
+  /**
+   * Matched rows that were NOT removed because their path could not be read
+   * (EACCES, EPERM, timeout): only ENOENT/ENOTDIR or a different declared id
+   * prove a project gone (T12471). Absent when none.
+   */
+  unreadable?: NexusProjectsCleanUnreadable[];
+  /**
+   * Matched rows that were NOT removed because their path exists but declares
+   * another project id (T12471). `.cleo/project-id` is tracked, so a branch
+   * checkout, rebase or merge conflict flips it transiently; only an absent
+   * path proves a project gone. Absent when none.
+   */
+  idMismatch?: NexusProjectsCleanIdMismatch[];
+}
+
+/** A registry row `nexus.projects.clean` kept because its path declares another id (T12471). */
+export interface NexusProjectsCleanIdMismatch {
+  /** Immutable registry project ID. */
+  projectId: string;
+  /** Registered path. */
+  projectPath: string;
+  /** The id the path declares now. */
+  declares: string;
+}
+
+/** A registry row `nexus.projects.clean` kept because its path was unreadable (T12471). */
+export interface NexusProjectsCleanUnreadable {
+  /** Immutable registry project ID. */
+  projectId: string;
+  /** Registered path that could not be read. */
+  projectPath: string;
+}
+
+/**
+ * A registry row `nexus.projects.clean` refused to remove because its project
+ * id was found at another path on this device (T12471).
+ */
+export interface NexusProjectsCleanRelocated {
+  /** Immutable registry project ID. */
+  projectId: string;
+  /** Registered path (gone from disk). */
+  projectPath: string;
+  /** Path(s) that declare the same id now. */
+  foundAt: string[];
+  /** Exact command that rebinds the row instead of deleting it. */
+  remedy: string;
+}
+
+/**
+ * Classification of one registry row by `cleo doctor projects` (T12471).
+ *
+ * - `ok` — the registered path holds the project.
+ * - `moved` — the path provably no longer holds it and another path on this
+ *   device declares the id. `--apply` rebinds the row only when that path's
+ *   untracked checkout nonce equals one recorded for the id (`proof:
+ *   'nonce'`); an `id-only` match (a clone, a copied `.cleo/project-id`) is
+ *   reported with the `cleo doctor project-identity --resolve` remedy and
+ *   never applied. Trash, CLEO-home, tombstoned and reroot-demoted paths are
+ *   never targets.
+ * - `ambiguous` — the path is gone and several paths carry the id's nonce;
+ *   the operator confirms one with `cleo doctor project-identity --resolve`.
+ * - `split` — one project under two ids, proven by repository evidence: the
+ *   registered path is gone and a same-named path with the same git remote or
+ *   root commit holds a different id (a re-minted identity), or two registered
+ *   rows, neither nested in another registered project, share a git remote.
+ *   Never changed automatically.
+ * - `possible-split` — the path is gone and a same-named path holds another
+ *   id, with no repository evidence tying them: informational (inspect, never
+ *   rewrite or unregister the other project). `--apply` still records the
+ *   gone location as `missing`.
+ * - `missing` — the path is gone and the id was found nowhere. `--apply`
+ *   records the location as `missing`; the row is kept.
+ * - `temp` — the path is under a temp directory while the registry is
+ *   persistent (a fixture or scratch directory left in the registry).
+ * - `root` — the path is the home directory or a filesystem root.
+ * - `unreadable` — the path could not be read (EACCES, EPERM, timeout). Only
+ *   ENOENT/ENOTDIR prove a path gone, so nothing is changed.
+ * - `other-device` — the path was recorded on another device; not probed.
+ */
+export type NexusRegistryFindingKind =
+  | 'ok'
+  | 'moved'
+  | 'ambiguous'
+  | 'split'
+  | 'possible-split'
+  | 'missing'
+  | 'temp'
+  | 'root'
+  | 'unreadable'
+  | 'other-device';
+
+/** The other side of a split identity (T12471). */
+export interface NexusRegistrySplitPeer {
+  /** The other project id. */
+  projectId: string;
+  /** Where the other id lives. */
+  projectPath: string;
+  /** Whether the other id has its own registry row. */
+  registered: boolean;
+  /** What paired the two ids: a shared git remote or root commit, or the directory name alone. */
+  matchedBy: 'name' | 'remote' | 'root-commit';
+}
+
+/** One registry row as classified by `cleo doctor projects` (T12471). */
+export interface NexusRegistryFinding {
+  /** Immutable registry project ID. */
+  projectId: string;
+  /** Registered project name. */
+  name: string;
+  /** Registered path (may be a `superseded:<id>` sentinel). */
+  projectPath: string;
+  /** Classification. */
+  kind: NexusRegistryFindingKind;
+  /** One-line explanation. */
+  message: string;
+  /** Exact command(s) that fix it, or `null` when nothing needs fixing. */
+  remedy: string | null;
+  /** `true` when `--apply` changes registry rows for this finding. */
+  applicable: boolean;
+  /** Paths on this device that declare this id (`moved`, `ambiguous`). */
+  foundAt?: string[];
+  /**
+   * What ties a `moved` checkout to the row: `nonce` when its untracked
+   * checkout nonce equals one recorded for the id (a real move), `id-only`
+   * when only the committed id matches.
+   */
+  proof?: 'nonce' | 'id-only';
+  /** The other ids of a `split` or `possible-split` identity. */
+  splitWith?: NexusRegistrySplitPeer[];
+}
+
+/**
+ * An alias key that more than one registered project claims (T12589).
+ *
+ * The legacy project id encodes only the first 24 bytes of a path, so every
+ * project under a long shared prefix derives the same key. Such a key names
+ * no project: resolvers refuse it, and `cleo doctor projects --apply` removes
+ * its alias row under a receipt.
+ */
+export interface NexusRegistryAmbiguousAlias {
+  /** The alias key (`nexus_project_id_aliases.legacy_id`). */
+  legacyId: string;
+  /** The project the alias row currently points at (the first to record it). */
+  canonicalId: string;
+  /** Every registered project that claims the key, sorted. */
+  claimants: string[];
+  /** One-line explanation. */
+  message: string;
+  /** Exact command that removes the row. */
+  remedy: string;
+}
+
+/** One registry change made by `cleo doctor projects --apply` (T12471). */
+export interface NexusRegistryRepairAction {
+  /**
+   * `rebind` points the row at `to`; `mark-missing` records the location as
+   * `missing`; `drop-ambiguous-alias` removes the alias row for `alias`
+   * (T12589).
+   */
+  action: 'rebind' | 'mark-missing' | 'drop-ambiguous-alias';
+  /** Project the action applies to (for an alias, the row's `canonical_id`). */
+  projectId: string;
+  /** Registered path before the action. */
+  from: string;
+  /** New registered path (`rebind` only). */
+  to?: string;
+  /** Alias key removed (`drop-ambiguous-alias` only). */
+  alias?: string;
+  /** `applied`, or `skipped` when the row changed between inspection and apply. */
+  outcome: 'applied' | 'skipped';
+}
+
+/** Durable receipt of an applied `cleo doctor projects` run (T12471). */
+export interface NexusRegistryRepairReceipt {
+  /** `nexus_audit_log.id` written in the same transaction as the changes. */
+  receiptId: string;
+  /** Absolute path of the global registry store that was changed. */
+  storePath: string;
+  /** ISO 8601 timestamp of the apply. */
+  appliedAt: string;
+  /** Every action, in order. */
+  actions: NexusRegistryRepairAction[];
+  /** Registry row count before and after; equal counts show no row was lost. */
+  registryRows: { before: number; after: number };
+  /** Exact command that restores the prior rows. */
+  rollback: string;
+}
+
+/** Result of `cleo doctor projects` (dry run or apply) (T12471). */
+export interface NexusRegistryIntegrityReport {
+  /** `true` when nothing was written. */
+  dryRun: boolean;
+  /** Absolute path of the global registry store inspected. */
+  storePath: string;
+  /** Directories scanned for `.cleo/project-id`. */
+  roots: string[];
+  /** Scan coverage: projects found, and directories that timed out or were unreadable. */
+  scan: { projectsFound: number; timedOut: string[]; unreadable: string[] };
+  /** Registry rows per kind; every row is counted. */
+  counts: Record<NexusRegistryFindingKind, number>;
+  /** Every row whose kind is not `ok`. */
+  findings: NexusRegistryFinding[];
+  /** Alias rows whose key more than one project claims (T12589). */
+  ambiguousAliases: NexusRegistryAmbiguousAlias[];
+  /** Receipt of the applied changes; absent on a dry run or when nothing applied. */
+  receipt?: NexusRegistryRepairReceipt;
+}
+
+/** Result of `cleo doctor projects --rollback <receiptId>` (T12471). */
+export interface NexusRegistryRollbackResult {
+  /** The receipt that was rolled back. */
+  receiptId: string;
+  /** `nexus_audit_log.id` of the rollback itself. */
+  rollbackReceiptId: string;
+  /** Rows written back per table (`aliases` when the repair removed alias rows). */
+  restored: { registry: number; locations: number; paths: number; aliases?: number };
 }
 
 /** Parameters for `nexus.refresh-bridge`. */
@@ -1702,6 +2114,7 @@ export type NexusOps = {
   readonly 'projects.remove': readonly [NexusProjectsRemoveParams, NexusProjectsRemoveResult];
   readonly 'projects.scan': readonly [NexusProjectsScanParams, NexusProjectsScanResult];
   readonly 'projects.clean': readonly [NexusProjectsCleanParams, NexusProjectsCleanResult];
+  readonly 'projects.status': readonly [NexusProjectsStatusParams, NexusProjectsStatusResult];
   readonly 'refresh-bridge': readonly [NexusRefreshBridgeParams, NexusRefreshBridgeResult];
   readonly diff: readonly [NexusDiffParams, NexusDiffResult];
   readonly 'query-cte': readonly [NexusQueryCteParams, NexusQueryCteResult];

package/src/operations/release.ts

@@ -2,6 +2,11 @@
  * Release Domain Operations (7 operations)
  *
  * All mutate operations
+ *
+ * Shared-surface taxonomy (T10483): this file also defines the contract that
+ * keeps shipped CLEO release commands and generated workflow templates aligned.
+ * The contract is intentionally data-only so downstream validators can assert
+ * the release pipeline without importing @cleocode/core or @cleocode/cleo.
  */
 
 /**
@@ -16,6 +21,198 @@ export interface ReleaseGate {
   reason?: string;
 }
 
+// ── T10483: release shared-surface command/template contract ────────────────
+
+/**
+ * Release-surface taxonomy used by T10468/T10476 to distinguish shipped CLEO
+ * consumer tooling, cleocode dogfood-only repository workflows, and contracts
+ * that are shared by both surfaces.
+ */
+export type ReleaseSurfaceAudience =
+  | 'shipped-consumer-tooling'
+  | 'cleocode-dogfood-workflow'
+  | 'shared-surface';
+
+/** Stability expectation for a release surface. */
+export type ReleaseSurfaceStability = 'public-contract' | 'internal-template';
+
+/** CLI or dispatch entry point participating in the release shared surface. */
+export interface ReleaseCommandSurfaceContract {
+  /** Human-facing command form, e.g. `cleo release plan`. */
+  command: string;
+  /** Dispatch gateway used by the shipped CLI command. */
+  gateway: 'query' | 'mutate';
+  /**
+   * Dispatch domain and operation, e.g. `release.plan`. Operations routed
+   * through the pipeline domain carry the `pipeline.` prefix.
+   */
+  operation: string;
+  /** Surface audience classification for release-product taxonomy. */
+  audience: ReleaseSurfaceAudience;
+  /** Compatibility/stability promise. */
+  stability: ReleaseSurfaceStability;
+  /** True when the command may write local deterministic state. */
+  writesLocalState: boolean;
+  /** True when the command may call GitHub/npm/network services. */
+  mayCallNetwork: boolean;
+  /** True when an LLM call may block success. MUST remain false for release surfaces. */
+  llmBlockingPath: false;
+  /** True when identical inputs and repo state yield the same release artifact. */
+  deterministic: boolean;
+  /** True when this surface must be covered by a changeset before release. */
+  changesetRequired: boolean;
+}
+
+/** Generated workflow template participating in the release shared surface. */
+export interface ReleaseTemplateSurfaceContract {
+  /** Template path in the source tree. */
+  template: string;
+  /** Rendered workflow filename installed into consumer repositories. */
+  renderedWorkflow: string;
+  /** Owning/recovering command that operators use for this workflow. */
+  owningCommand: string;
+  /** Surface audience classification for release-product taxonomy. */
+  audience: ReleaseSurfaceAudience;
+  /** Compatibility/stability promise. */
+  stability: ReleaseSurfaceStability;
+  /** True when template execution may call GitHub/npm/network services. */
+  mayCallNetwork: boolean;
+  /** True when an LLM call may block success. MUST remain false for release surfaces. */
+  llmBlockingPath: false;
+  /** True when the template consumes a precomputed deterministic plan. */
+  consumesReleasePlan: boolean;
+  /** True when template drift must be snapshot/render tested. */
+  renderSnapshotRequired: boolean;
+}
+
+/**
+ * Shipped release commands that form the public/operator contract.  The first
+ * verb, `plan`, is deliberately deterministic and network-free: release
+ * planning must be a changesets-first local computation, not an LLM-first or
+ * GitHub-first blocking path.
+ */
+export const RELEASE_SHARED_COMMAND_SURFACES = [
+  {
+    command: 'cleo release plan',
+    gateway: 'mutate',
+    operation: 'release.plan',
+    audience: 'shared-surface',
+    stability: 'public-contract',
+    writesLocalState: true,
+    mayCallNetwork: false,
+    llmBlockingPath: false,
+    deterministic: true,
+    changesetRequired: true,
+  },
+  {
+    command: 'cleo release open',
+    gateway: 'mutate',
+    operation: 'release.open',
+    audience: 'shared-surface',
+    stability: 'public-contract',
+    writesLocalState: true,
+    mayCallNetwork: true,
+    llmBlockingPath: false,
+    deterministic: false,
+    changesetRequired: true,
+  },
+  {
+    command: 'cleo release reconcile',
+    gateway: 'mutate',
+    operation: 'release.reconcile',
+    audience: 'shared-surface',
+    stability: 'public-contract',
+    writesLocalState: true,
+    mayCallNetwork: true,
+    llmBlockingPath: false,
+    deterministic: true,
+    changesetRequired: true,
+  },
+  {
+    command: 'cleo release rollback',
+    gateway: 'mutate',
+    operation: 'pipeline.release.rollback',
+    audience: 'shipped-consumer-tooling',
+    stability: 'public-contract',
+    writesLocalState: true,
+    mayCallNetwork: false,
+    llmBlockingPath: false,
+    deterministic: true,
+    changesetRequired: true,
+  },
+] as const satisfies readonly ReleaseCommandSurfaceContract[];
+
+/**
+ * Workflow templates that must stay in parity with the release command surface.
+ *
+ * Every entry is a SHIPPED template (registered as kind `workflow` in the core
+ * template manifest and rendered into consumer repositories), so none is
+ * classified `cleocode-dogfood-workflow`: that audience is reserved for the
+ * cleocode repository's own `.github/workflows/*.yml` owner CI, which is never
+ * installed into consumers. `release-prepare` and `release-publish` bind to a
+ * public release verb and consume the release plan; `release-rollback` records
+ * through `cleo release reconcile --rollback`, and `release-fanout` runs on the
+ * GitHub `release: published` event with no CLEO verb of its own, so its
+ * recovering command is the template refresh surface `cleo upgrade workflows`.
+ */
+export const RELEASE_SHARED_TEMPLATE_SURFACES = [
+  {
+    template: 'packages/core/templates/workflows/release-prepare.yml.tmpl',
+    renderedWorkflow: 'release-prepare.yml',
+    owningCommand: 'cleo release open',
+    audience: 'shared-surface',
+    stability: 'public-contract',
+    mayCallNetwork: true,
+    llmBlockingPath: false,
+    consumesReleasePlan: true,
+    renderSnapshotRequired: true,
+  },
+  {
+    template: 'packages/core/templates/workflows/release-publish.yml.tmpl',
+    renderedWorkflow: 'release-publish.yml',
+    owningCommand: 'cleo release reconcile',
+    audience: 'shared-surface',
+    stability: 'public-contract',
+    mayCallNetwork: true,
+    llmBlockingPath: false,
+    consumesReleasePlan: true,
+    renderSnapshotRequired: true,
+  },
+  {
+    template: 'packages/core/templates/workflows/release-rollback.yml.tmpl',
+    renderedWorkflow: 'release-rollback.yml',
+    owningCommand: 'cleo release reconcile',
+    audience: 'shipped-consumer-tooling',
+    stability: 'internal-template',
+    mayCallNetwork: true,
+    llmBlockingPath: false,
+    consumesReleasePlan: false,
+    renderSnapshotRequired: true,
+  },
+  {
+    template: 'packages/core/templates/workflows/release-fanout.yml.tmpl',
+    renderedWorkflow: 'release-fanout.yml',
+    owningCommand: 'cleo upgrade workflows',
+    audience: 'shipped-consumer-tooling',
+    stability: 'internal-template',
+    mayCallNetwork: true,
+    llmBlockingPath: false,
+    consumesReleasePlan: false,
+    renderSnapshotRequired: true,
+  },
+] as const satisfies readonly ReleaseTemplateSurfaceContract[];
+
+/** All commands/templates that share the release-product contract. */
+export const RELEASE_SHARED_SURFACE_CONTRACT = {
+  commands: RELEASE_SHARED_COMMAND_SURFACES,
+  templates: RELEASE_SHARED_TEMPLATE_SURFACES,
+  invariants: {
+    deterministicPlanningCommand: 'cleo release plan',
+    llmBlockingPathAllowed: false,
+    changesetRequiredForPublicCommands: true,
+  },
+} as const;
+
 /**
  * Mutate Operations
  */

package/src/operations/session.ts

@@ -613,12 +613,14 @@ export interface SessionEndParams {
   /**
    * Explicit session id to end (T11346 · Epic T11284).
    *
-   * When omitted, session-end targets the CALLER's session resolved env-first
-   * (`CLEO_SESSION_ID` → … → most-recent active). When provided, this id
-   * overrides env/active resolution. Either way, one agent can no longer end a
-   * different concurrently-active agent's session implicitly.
+   * When omitted, session-end targets the CALLER's bound session (connection
+   * handle → `CLEO_SESSION_ID` → terminal binding). An unbound caller gets
+   * `E_SESSION_UNBOUND` while any session is active — the newest active row is
+   * never the implicit target (T12500). When provided, this id overrides
+   * resolution (CLI: `cleo session end --session <id>`).
    *
    * @task T11346
+   * @task T12500
    */
   sessionId?: string;
 }