@cleocode/contracts 2026.5.96 → 2026.5.98

package/src/operations/session.ts

@@ -65,6 +65,11 @@ export interface SessionListParams {
   status?: string;
   limit?: number;
   offset?: number;
+  /**
+   * When true, surface all columns including per-agent fields added in T9975
+   * (agentHandle, scopeKind, scopeId, lastActivity).
+   */
+  all?: boolean;
 }
 /** Result of `session.list`. */
 export interface SessionListResult {
@@ -295,6 +300,38 @@ export interface SessionBriefingShowParams {
   scope?: string;
   /** When true, exit non-zero if any contract violation is detected (T1905). */
   strict?: boolean;
+  /**
+   * Explicit session ID to scope the briefing to (T9975).
+   *
+   * When provided, the briefing resolution uses this session ID instead of
+   * inferring from env vars or most-recent active session. Internal use only.
+   */
+  activeSessionId?: string;
+  /**
+   * When true, include `peerPatterns` in the warm bundle and other verbose
+   * debug fields that are suppressed by default to reduce token count.
+   *
+   * @task T9974
+   */
+  debug?: boolean;
+  /**
+   * When true, include `cold.userProfile` traits in the bundle.
+   * Suppressed by default (large trait dump rarely needed at session start).
+   *
+   * @task T9974
+   */
+  withProfile?: boolean;
+  /**
+   * When true, restore full text fields on peerLearnings and decisions
+   * (the `insight` and `decision` body fields respectively). By default
+   * these are stripped and only `{id, title, createdAt, _next}` is emitted
+   * to reduce token consumption (T9964 Part 1 follow-up).
+   *
+   * Alias: `--memory-detail` on the CLI.
+   *
+   * @task T9964
+   */
+  memoryDetail?: boolean;
 }
 
 /** Compact task entry in a session briefing's next-tasks list. */
@@ -504,6 +541,34 @@ export interface SessionStartParams {
    * and validated on every `CLEO_OWNER_OVERRIDE` call.
    */
   ownerAuthToken?: string;
+  /**
+   * Human-readable agent handle for multi-agent isolation (T9975).
+   *
+   * When provided, the conflict check is scoped per-agent-handle: multiple
+   * sessions with different handles may be active simultaneously, enabling
+   * N-agent parallel execution without briefing surface collisions.
+   *
+   * Stored in `sessions.agent_handle`. Surfaced in `cleo session list --all`.
+   *
+   * @example "agent-A", "worker-T9975", "ct-task-executor"
+   */
+  agentHandle?: string;
+}
+
+// session.adopt
+/** Parameters for `session.adopt`. */
+export interface SessionAdoptParams {
+  /** Session ID to rebind the current env to. */
+  sessionId: string;
+}
+/** Result of `session.adopt`. */
+export interface SessionAdoptResult {
+  /** The session being adopted. */
+  sessionId: string;
+  /** Shell export command to rebind env — print and eval in the calling shell. */
+  exportCommand: string;
+  /** Name of the env variable set. */
+  envVar: 'CLEO_SESSION_ID';
 }
 // session.end
 /** Parameters for `session.end`. */
@@ -690,4 +755,6 @@ export type SessionOps = {
     SessionRecordAssumptionResult,
   ];
   readonly lint: readonly [SessionLintParams, SessionLintResult];
+  /** Rebind env to a specific session (T9975). */
+  readonly adopt: readonly [SessionAdoptParams, SessionAdoptResult];
 };

package/src/operations/tasks.ts

@@ -35,6 +35,7 @@ import type {
   TaskTreeNode,
   TaskView,
 } from '../tasks.js';
+import type { DocsType } from './docs.js';
 
 export type { TaskPriority, TaskStatus };
 
@@ -146,17 +147,56 @@ export interface TasksShowParams {
   /** When true, include IVTR phase history. */
   ivtrHistory?: boolean;
 }
+
+/**
+ * Minimal attachment entry surfaced in the `tasks.show` envelope.
+ *
+ * A lightweight projection of a docs attachment — enough to identify and
+ * navigate to the full attachment via `cleo docs fetch <slug|id>`, without
+ * the full byte payload.
+ *
+ * Fields are a subset of {@link import('./docs.js').DocsAttachmentRow}:
+ *   - `attachmentId` — store ID (att_* or UUID)
+ *   - `slug`         — human-friendly name (present when set on `cleo docs add`)
+ *   - `type`         — taxonomy classification (e.g. 'adr', 'research')
+ *   - `kind`         — storage kind ('local-file', 'url', 'blob', etc.)
+ *
+ * @task T9966
+ * @epic T9964
+ */
+export interface TaskShowAttachmentEntry {
+  /** Attachment identifier (att_* or UUID). */
+  attachmentId: string;
+  /** Human-friendly slug, unique per project. Present when assigned at add time. */
+  slug?: string;
+  /** Taxonomy classification. Present when assigned at add time. */
+  type?: DocsType;
+  /** Storage kind — discriminant for the full attachment variant. */
+  kind: string;
+}
+
 /**
  * Result of `tasks.show` — the full task record plus its canonical view
  * projection. `view` is null when the task has no lifecycle pipeline.
  *
  * @task T1703
+ * @task T9966 — attachments[] always present (empty array when none)
  */
 export interface TasksShowResult {
   /** Full task record (string-widened for dispatch layer serialization). */
   task: TaskRecord;
   /** Canonical task view projection produced by `computeTaskView`. Null when unavailable. */
   view: TaskView | null;
+  /**
+   * Attachments linked to this task via the docs store.
+   *
+   * Always an array — empty (`[]`) when no attachments exist. Never `null`.
+   * Each entry carries enough context to navigate to the full attachment
+   * via `cleo docs fetch <slug|attachmentId>`.
+   *
+   * @task T9966
+   */
+  attachments: TaskShowAttachmentEntry[];
 }
 
 // tasks.tree dispatch params (with optional withBlockers flag — dispatch alias)

package/src/provenance.ts

@@ -0,0 +1,335 @@
+/**
+ * Provenance graph union types.
+ *
+ * Canonical home for the 16 string-literal union types that describe edges
+ * and FSM states in the CLEO provenance graph (commits, pull requests,
+ * releases, release artifacts, and BRAIN↔release links). Promoted from
+ * `packages/core/src/store/tasks-schema.ts` in Phase 0c of the
+ * SG-ARCH-SOLID Saga so that downstream packages can import these unions
+ * without pulling in the Drizzle schema runtime.
+ *
+ * The const arrays that back each union (`PR_STATES`, `COMMIT_LINK_KINDS`,
+ * `RELEASE_STATUSES`, …) remain in `tasks-schema.ts` because Drizzle's
+ * `text({ enum: ... })` column declaration narrows the runtime row type
+ * directly from those `as const` literals. `tasks-schema.ts` re-exports
+ * each union from this module to preserve the existing public surface for
+ * every `import * as schema from '../store/tasks-schema.js'` consumer.
+ *
+ * @see SPEC-T9345 §3 — provenance graph table definitions
+ * @see ADR-073 — task hierarchy charter (release provenance scope)
+ *
+ * Consolidated unions:
+ *   - {@link PrState}                   — pull-request lifecycle state
+ *   - {@link PrLinkSource}              — how a PR↔task link was discovered
+ *   - {@link PrLinkKind}                — semantic PR↔task relationship
+ *   - {@link CommitConventionalType}    — Conventional Commits prefix
+ *   - {@link CommitLinkKind}            — semantic commit↔task relationship
+ *   - {@link CommitLinkSource}          — how a commit↔task link was discovered
+ *   - {@link CommitFileChangeType}      — git status letter (A/M/D/R/C)
+ *   - {@link ReleaseScheme}             — versioning scheme
+ *   - {@link ReleaseChannel}            — npm dist-tag channel
+ *   - {@link ReleaseKind}               — release packaging type
+ *   - {@link ReleaseStatus}             — unified release FSM state
+ *   - {@link ReleaseChangeType}         — 12-value change taxonomy
+ *   - {@link ReleaseImpact}             — semver impact level
+ *   - {@link ReleaseClassifiedBy}       — change-classification provenance
+ *   - {@link ReleaseArtifactType}       — artifact archetype
+ *   - {@link BrainReleaseLinkType}      — BRAIN↔release link semantics
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+// ── Pull-request unions (T9507) ─────────────────────────────────────────
+
+/**
+ * State of a pull request.
+ *
+ * Mirrors the GitHub PR state machine:
+ *   - `open`   — PR is open and not yet merged
+ *   - `closed` — PR was closed without merging
+ *   - `merged` — PR was merged into the target branch
+ *
+ * @task T9507
+ */
+export type PrState = 'open' | 'closed' | 'merged';
+
+/**
+ * How a PR↔task link was discovered.
+ *
+ *   - `pr-title`       — task ID matched in the PR title
+ *   - `pr-body`        — task ID matched in the PR body markdown
+ *   - `branch-name`    — parsed from the branch name (e.g. `feat/T9507-...`)
+ *   - `commit-trailer` — extracted from a git trailer in a PR commit
+ *   - `manual`         — explicitly linked via `cleo provenance link`
+ *
+ * @task T9507
+ */
+export type PrLinkSource = 'pr-title' | 'pr-body' | 'branch-name' | 'commit-trailer' | 'manual';
+
+/**
+ * Semantic classification of a PR↔task relationship.
+ *
+ * Extends {@link CommitLinkKind} with `'tracks'` for PRs that observe a
+ * task without directly implementing, fixing, or documenting it.
+ *
+ *   - `implements` — the PR directly implements the task's acceptance criteria
+ *   - `fixes`      — the PR fixes a bug or regression in the task's work
+ *   - `refactors`  — the PR restructures code introduced by the task
+ *   - `tests`      — the PR adds or updates tests for the task
+ *   - `docs`       — the PR updates documentation for the task
+ *   - `reverts`    — the PR reverts work introduced by the task
+ *   - `tracks`     — the PR is related to but does not directly implement the task
+ *
+ * @task T9507
+ */
+export type PrLinkKind =
+  | 'implements'
+  | 'fixes'
+  | 'refactors'
+  | 'tests'
+  | 'docs'
+  | 'reverts'
+  | 'tracks';
+
+// ── Commit unions (T9506) ───────────────────────────────────────────────
+
+/**
+ * Conventional Commits prefix parsed from a commit subject.
+ *
+ * Adds `'breaking'` to the canonical CC set to flag BREAKING CHANGE
+ * footers. The DB column is nullable — a commit that does not follow
+ * Conventional Commits format stores NULL rather than one of these values.
+ *
+ * @task T9506
+ */
+export type CommitConventionalType =
+  | 'feat'
+  | 'fix'
+  | 'chore'
+  | 'docs'
+  | 'refactor'
+  | 'test'
+  | 'build'
+  | 'ci'
+  | 'perf'
+  | 'revert'
+  | 'breaking';
+
+/**
+ * Semantic classification of a commit↔task relationship.
+ *
+ *   - `implements` — the commit directly implements the task's acceptance criteria
+ *   - `fixes`      — the commit fixes a bug or regression in the task's work
+ *   - `refactors`  — the commit restructures code introduced by the task
+ *   - `tests`      — the commit adds or updates tests for the task
+ *   - `docs`       — the commit updates documentation for the task
+ *   - `reverts`    — the commit reverts work introduced by the task
+ *
+ * @task T9506
+ */
+export type CommitLinkKind = 'implements' | 'fixes' | 'refactors' | 'tests' | 'docs' | 'reverts';
+
+/**
+ * How a commit↔task link was discovered.
+ *
+ *   - `commit-trailer` — extracted from a `T####:` or `Task-Id:` git trailer
+ *   - `commit-subject` — matched `T####` regex in the commit subject line
+ *   - `pr-title`       — matched task ID in the PR title
+ *   - `pr-body`        — matched task ID in the PR body markdown
+ *   - `branch-name`    — parsed from the branch name (e.g., `feat/T9506-...`)
+ *   - `manual`         — explicitly linked via `cleo provenance link`
+ *
+ * @task T9506
+ */
+export type CommitLinkSource =
+  | 'commit-trailer'
+  | 'commit-subject'
+  | 'pr-title'
+  | 'pr-body'
+  | 'branch-name'
+  | 'manual';
+
+/**
+ * Per-file change type from a git diff (status letter codes).
+ *
+ *   - `A` — added
+ *   - `M` — modified
+ *   - `D` — deleted
+ *   - `R` — renamed
+ *   - `C` — copied
+ *
+ * @task T9506
+ */
+export type CommitFileChangeType = 'A' | 'M' | 'D' | 'R' | 'C';
+
+// ── Release unions (T9508) ──────────────────────────────────────────────
+
+/**
+ * Versioning scheme for a release.
+ *
+ *   - `calver`        — YYYY.MM.patch (e.g. 2026.5.74) — CLEO default
+ *   - `semver`        — MAJOR.MINOR.PATCH (e.g. 1.2.3)
+ *   - `calver-suffix` — YYYY.MM.patch.N suffix hotfix (e.g. 2026.5.74.2)
+ *
+ * @task T9508
+ * @remarks
+ * The values here MUST stay aligned with `RELEASE_SCHEMES` in
+ * `tasks-schema.ts`; that const array drives the Drizzle row type. A
+ * compile-time structural assertion in
+ * `packages/contracts/src/__tests__/provenance.test.ts` pins both sides.
+ */
+export type ReleaseScheme = 'calver' | 'semver' | 'calver-suffix';
+
+/**
+ * Release channel — controls which npm dist-tag (or equivalent) the
+ * artifact is published under.
+ *
+ *   - `latest` — current stable
+ *   - `beta`   — pre-release tested in production-adjacent environments
+ *   - `dev`    — internal development snapshots
+ *   - `hotfix` — emergency patch outside the regular cadence
+ *
+ * @task T9508
+ * @remarks
+ * Distinct from the `ReleaseChannel` exported by
+ * `@cleocode/contracts/release/channel` (which carries the npm-level
+ * `latest|beta|alpha` set) and from the `ReleaseChannel` in
+ * `@cleocode/contracts/release/plan` (which carries the release-plan
+ * `latest|beta|alpha|rc` set). Top-level `@cleocode/contracts` re-exports
+ * this union under a disambiguating alias.
+ */
+export type ReleaseChannel = 'latest' | 'beta' | 'dev' | 'hotfix';
+
+/**
+ * Release packaging kind, orthogonal to individual change types within
+ * the release.
+ *
+ *   - `regular`    — standard scheduled release
+ *   - `hotfix`     — emergency patch outside regular cadence
+ *   - `prerelease` — alpha/beta/rc release for early adopters
+ *
+ * @task T9508
+ */
+export type ReleaseKind = 'regular' | 'hotfix' | 'prerelease';
+
+/**
+ * Unified release FSM state (admits values from BOTH the new T9492
+ * pipeline and the legacy T5580 pipeline; the status value itself
+ * discriminates which pipeline owns the row).
+ *
+ * **New T9492 pipeline** — SPEC-T9345 §10.1 FSM:
+ *   `planned → pr-opened → pr-merged → published → reconciled`
+ *
+ * **Legacy T5580 pipeline** — pre-T9492 12-step flow:
+ *   `prepared → committed → tagged → pushed`
+ *
+ * **Shared terminal states**:
+ *   `rolled_back | failed | cancelled`
+ *
+ * State transitions per R-302 MUST be monotonic within each lifecycle;
+ * illegal transitions return `E_INVALID_STATE` and MUST NOT mutate any row.
+ *
+ * @task T9508
+ * @task T9686 (unification — legacy + new statuses on one column)
+ * @see SPEC-T9345 §10.1
+ */
+export type ReleaseStatus =
+  | 'planned'
+  | 'pr-opened'
+  | 'pr-merged'
+  | 'published'
+  | 'reconciled'
+  | 'prepared'
+  | 'committed'
+  | 'tagged'
+  | 'pushed'
+  | 'rolled_back'
+  | 'failed'
+  | 'cancelled';
+
+/**
+ * 12-value CLEO release change taxonomy (Option B from
+ * provenance-graph-design.md §2.2).
+ *
+ * Lives at the release-changes level (not on `tasks.kind`) so that:
+ *   - A single task can produce multiple change rows across releases.
+ *   - Hotfix classification is a release-packaging decision, not a task property.
+ *   - Auto-classification is agent-writable without touching OWNER-WRITE-ONLY fields.
+ *
+ * @task T9508
+ * @see SPEC-T9345 §2.2
+ */
+export type ReleaseChangeType =
+  | 'feature'
+  | 'enhancement'
+  | 'bug'
+  | 'hotfix'
+  | 'security'
+  | 'breaking'
+  | 'refactor'
+  | 'docs'
+  | 'chore'
+  | 'revert'
+  | 'deprecation'
+  | 'infrastructure';
+
+/**
+ * Impact level for a release change, mapped to semver bump assessment.
+ *
+ *   - `major` — breaking change (MAJOR bump)
+ *   - `minor` — new feature (MINOR bump)
+ *   - `patch` — bug fix / chore (PATCH bump)
+ *   - `none`  — cosmetic / docs / trivial (no version bump warranted alone)
+ *
+ * @task T9508
+ */
+export type ReleaseImpact = 'major' | 'minor' | 'patch' | 'none';
+
+/**
+ * Provenance of a release-change classification.
+ *
+ *   - `auto`     — derived by the classification engine from CC prefix + heuristics
+ *   - `manual`   — owner overrode the auto classification via `cleo release classify`
+ *   - `approved` — owner approved an agent-proposed classification
+ *
+ * @task T9508
+ */
+export type ReleaseClassifiedBy = 'auto' | 'manual' | 'approved';
+
+// ── Release artifact + BRAIN-link unions (T9509) ─────────────────────────
+
+/**
+ * Release artifact archetype.
+ *
+ *   - `npm`            — npm package published to a registry
+ *   - `cargo`          — Rust crate published to crates.io
+ *   - `docker`         — Container image pushed to an OCI registry
+ *   - `pypi`           — Python package published to pypi.org
+ *   - `github-release` — GitHub Releases asset attached to a git tag
+ *   - `binary`         — Generic compiled binary distributed via direct URL
+ *   - `github-tag`     — Lightweight git tag (no attached assets)
+ *
+ * @task T9509
+ * @see SPEC-T9345 §3.9
+ */
+export type ReleaseArtifactType =
+  | 'npm'
+  | 'cargo'
+  | 'docker'
+  | 'pypi'
+  | 'github-release'
+  | 'binary'
+  | 'github-tag';
+
+/**
+ * Semantic relationship between a BRAIN entry and a release.
+ *
+ *   - `approved-by`    — A BRAIN decision approved a change that shipped in this release.
+ *   - `documented-in`  — This release is where the BRAIN entry was first formally documented.
+ *   - `derived-from`   — The release's failure or outcome produced this BRAIN learning/pattern.
+ *   - `observed-in`    — A BRAIN observation was made about this release (e.g. performance note).
+ *
+ * @task T9509
+ * @see SPEC-T9345 §8.1
+ */
+export type BrainReleaseLinkType = 'approved-by' | 'documented-in' | 'derived-from' | 'observed-in';

package/src/scaffold-diagnostics.ts

@@ -0,0 +1,119 @@
+/**
+ * Scaffold + diagnostic result contracts.
+ *
+ * Canonical home for the result shapes produced by CLEO's directory/file
+ * scaffolding utilities (`ensure*`) and read-only health-check utilities
+ * (`check*`). Promoted to `@cleocode/contracts` in Phase 0a of the
+ * SG-ARCH-SOLID Saga to eliminate duplicate definitions that previously
+ * lived in `packages/core/src/scaffold.ts`, `injection.ts`, `hooks.ts`,
+ * `schema-management.ts`, and `validation/doctor/checks.ts`.
+ *
+ * Consolidated types:
+ *   - {@link ScaffoldResult} — was defined 3× in core (scaffold/injection/hooks)
+ *   - {@link CheckStatus}   — was defined 2× in core (scaffold/doctor checks)
+ *   - {@link CheckResult}   — was defined 2× in core (scaffold/doctor checks)
+ *   - {@link HookCheckResult} — single canonical definition (no prior duplication;
+ *     promoted here to keep all scaffold-diagnostic shapes co-located)
+ *
+ * NOT consolidated (intentional — different domain shape):
+ *   - `CheckResult` in `packages/core/src/schema-management.ts` is a
+ *     `{ ok, installed, bundled, missing, stale }` schema-install report,
+ *     unrelated to diagnostic checks. It retains its local definition and
+ *     will be renamed in a follow-up slice if/when its naming collision
+ *     warrants a separate cleanup task.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+
+// ── ScaffoldResult ────────────────────────────────────────────────────
+
+/**
+ * Result of an `ensure*` scaffolding operation.
+ *
+ * All ensure functions in `@cleocode/core` are idempotent — they may
+ * create, repair, or skip the requested resource and report which
+ * action they took.
+ *
+ * Originally defined in:
+ *   - `packages/core/src/scaffold.ts`
+ *   - `packages/core/src/injection.ts`
+ *   - `packages/core/src/hooks.ts`
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export interface ScaffoldResult {
+  /** What action was taken: created, repaired, or skipped. */
+  action: 'created' | 'repaired' | 'skipped';
+  /** Filesystem path that was operated on. */
+  path: string;
+  /** Human-readable explanation of the result. */
+  details?: string;
+}
+
+// ── CheckStatus + CheckResult ─────────────────────────────────────────
+
+/**
+ * Status of a `check*` diagnostic.
+ *
+ * Originally defined in:
+ *   - `packages/core/src/scaffold.ts`
+ *   - `packages/core/src/validation/doctor/checks.ts`
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export type CheckStatus = 'passed' | 'failed' | 'warning' | 'info';
+
+/**
+ * Result of a `check*` diagnostic (used by `cleo doctor` and scaffold
+ * health checks).
+ *
+ * Originally defined in:
+ *   - `packages/core/src/scaffold.ts`
+ *   - `packages/core/src/validation/doctor/checks.ts`
+ *
+ * The scaffold.ts and doctor/checks.ts definitions were structurally
+ * identical; this is the consolidated shape with TSDoc preserved.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export interface CheckResult {
+  /** Unique check identifier (e.g. "cleo_structure", "sqlite_db"). */
+  id: string;
+  /** Category grouping (e.g. "scaffold", "global"). */
+  category: string;
+  /** Diagnostic outcome: passed, failed, warning, or info. */
+  status: CheckStatus;
+  /** Human-readable description of the check result. */
+  message: string;
+  /** Structured metadata about the check (paths, sizes, missing items). */
+  details: Record<string, unknown>;
+  /** Suggested CLI command to fix the issue, or null if passed. */
+  fix: string | null;
+}
+
+// ── HookCheckResult ───────────────────────────────────────────────────
+
+/**
+ * Result of a git-hook installation check.
+ *
+ * Reports whether a managed hook (commit-msg, pre-commit, pre-push) is
+ * installed in `.git/hooks/` and whether the installed copy matches the
+ * source template under `packages/core/templates/git-hooks/`.
+ *
+ * Originally defined in `packages/core/src/hooks.ts`. Promoted here to
+ * co-locate all scaffold-diagnostic shapes.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export interface HookCheckResult {
+  /** Hook name (commit-msg, pre-commit, pre-push). */
+  hook: string;
+  /** Whether the hook is installed at `.git/hooks/<hook>`. */
+  installed: boolean;
+  /** Whether the installed hook bytes match the source template. */
+  current: boolean;
+  /** Absolute path of the source template that should be installed. */
+  sourcePath: string;
+  /** Absolute path where the hook is (or would be) installed. */
+  installedPath: string;
+}

package/src/session.ts

@@ -137,6 +137,43 @@ export interface Session {
   gradeMode?: boolean;
   /** ID of the provider adapter used for this session. @defaultValue undefined */
   providerId?: string | null;
+  /**
+   * Human-readable agent handle for multi-agent isolation (T9975).
+   *
+   * Set via `cleo session start --agent <handle>`. Allows concurrent agent
+   * sessions to be distinguished in `cleo session list --all` and enables
+   * `cleo briefing` env-precedence detection when `CLEO_SESSION_ID` is set.
+   *
+   * @defaultValue undefined
+   */
+  agentHandle?: string | null;
+  /**
+   * Denormalised scope type ("global" | "epic") for fast index queries (T9975).
+   *
+   * Derived from `scope.type` at session creation; cached in the DB column
+   * `scope_kind` to avoid JSON parsing in hot paths.
+   *
+   * @defaultValue undefined
+   */
+  scopeKind?: string | null;
+  /**
+   * Denormalised scope target ID (e.g. "T9964") for epic sessions (T9975).
+   *
+   * Derived from `scope.epicId` / `scope.rootTaskId` at session creation.
+   * NULL for global sessions.
+   *
+   * @defaultValue undefined
+   */
+  scopeId?: string | null;
+  /**
+   * ISO 8601 timestamp of the last mutation on this session (T9975).
+   *
+   * Updated on session start, task focus change, and task completion.
+   * Used by the idle auto-end lifecycle hook and `cleo session list --all`.
+   *
+   * @defaultValue undefined
+   */
+  lastActivity?: string | null;
 }
 
 /**