@cleocode/core 2026.6.13 → 2026.6.15

package/dist/store/service-trust-gate.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Service-vault trust gate — **policy-before-decrypt** per-agent access control.
+ *
+ * EP-UNIVERSAL-SERVICE-VAULT (epic T11765 · saga SG-VAULT-CORE T10409 · M2 W1a ·
+ * task T11937 · AC4). Ports onecli `connect.rs` selective-mode: an agent may use a
+ * service connection ONLY when (a) a row exists in `agent_service_grants` linking
+ * the agent to the connection, AND (b) the grant's `session_policy` evaluates to
+ * an allow. This module evaluates that decision from already-loaded grant data —
+ * it performs ZERO crypto. The store
+ * ({@link import('./service-connections-accessor.js')}) calls `decryptGlobal`
+ * ONLY after this gate returns `allowed: true`, so a denied/blocked agent NEVER
+ * triggers a decrypt (the policy-before-decrypt invariant, proven by unit test).
+ *
+ * ## Why the gate is decrypt-free
+ *
+ * The gate takes the grant rows as INPUT and returns a pure decision. It cannot
+ * decrypt even if it wanted to — it imports no crypto. The decryption chokepoint
+ * lives one layer up (the accessor), guarded by this decision. That separation is
+ * exactly what makes "a denied agent never decrypts" structurally true and
+ * spy-assertable: the spy is placed on `decryptGlobal`, and a deny path returns
+ * before the accessor reaches the decrypt call.
+ *
+ * ## Policy shape ({@link SessionPolicy})
+ *
+ * Mirrors onecli's `PolicyAction` (block / rate-limit / manual-approval) collapsed
+ * to a per-grant JSON:
+ *
+ *   - `mode: 'allow' | 'block'` — `block` is a hard deny (no decrypt).
+ *   - `rateLimit?` — advisory rate cap; the gate surfaces it but does not itself
+ *     count requests (the caller enforces). Presence alone does not deny.
+ *   - `manualApproval?: true` — the connection requires an out-of-band human
+ *     approval that has not been granted for this session → deny (no decrypt)
+ *     until the caller supplies `approved: true` in the evaluation context.
+ *
+ * A bare grant (`{"mode":"allow"}`, the column default) allows.
+ *
+ * @module store/service-trust-gate
+ * @task T11937
+ * @epic T11765
+ * @saga T10409
+ * @see ./service-connections-accessor.ts — the accessor that decrypts ONLY on allow
+ * @see ../../../onecli — `apps/gateway/src/connect.rs` selective-mode (the ported model)
+ */
+/**
+ * Advisory rate-limit clause on a {@link SessionPolicy}.
+ *
+ * The gate reports it on an allow decision; it does NOT itself maintain a counter
+ * (the consumer enforces the cap). Presence never denies access — it shapes how
+ * the caller throttles an already-permitted credential use.
+ *
+ * @task T11937
+ */
+export interface SessionRateLimit {
+    /** Maximum requests permitted within `window`. */
+    readonly maxRequests: number;
+    /** Rolling window the cap applies over. */
+    readonly window: 'minute' | 'hour' | 'day';
+}
+/**
+ * Per-grant session policy evaluated by the trust gate BEFORE any decrypt.
+ *
+ * Serialized as the `agent_service_grants.session_policy` JSON column. The column
+ * default `{"mode":"allow"}` makes a bare grant permissive.
+ *
+ * @task T11937
+ */
+export interface SessionPolicy {
+    /** `block` is a hard deny (no decrypt); `allow` permits (subject to other clauses). */
+    readonly mode: 'allow' | 'block';
+    /** Advisory rate cap surfaced on an allow decision (never itself denies). */
+    readonly rateLimit?: SessionRateLimit;
+    /**
+     * When `true`, the connection requires an out-of-band human approval. The gate
+     * DENIES unless the evaluation context carries `approved: true` for this
+     * session.
+     */
+    readonly manualApproval?: boolean;
+}
+/**
+ * Minimal grant projection the gate evaluates — exactly the
+ * `agent_service_grants` columns the decision needs, no token material.
+ *
+ * @task T11937
+ */
+export interface ServiceGrant {
+    /** The granted agent. */
+    readonly agentId: string;
+    /** The connection this grant authorizes. */
+    readonly serviceConnectionId: number;
+    /** The parsed {@link SessionPolicy} (already JSON-decoded from the column). */
+    readonly sessionPolicy: SessionPolicy;
+}
+/**
+ * Context for a single access evaluation.
+ *
+ * @task T11937
+ */
+export interface TrustEvalContext {
+    /** The agent requesting access. */
+    readonly agentId: string;
+    /** The connection the agent wants to use. */
+    readonly serviceConnectionId: number;
+    /**
+     * Whether an out-of-band manual approval has been granted for this session.
+     * Required to pass a `manualApproval: true` policy. Defaults to `false`.
+     */
+    readonly approved?: boolean;
+}
+/**
+ * Reason an access evaluation was DENIED — stable codes for diagnostics/audit.
+ *
+ * @task T11937
+ */
+export type TrustDenyReason = 'no-grant' | 'policy-block' | 'manual-approval-required';
+/**
+ * The pure decision returned by {@link evaluateServiceAccess}.
+ *
+ * On `allowed: false` the accessor MUST NOT decrypt. On `allowed: true` the
+ * accessor may decrypt and (optionally) honor `rateLimit`.
+ *
+ * @task T11937
+ */
+export type TrustDecision = {
+    readonly allowed: true;
+    readonly rateLimit?: SessionRateLimit;
+} | {
+    readonly allowed: false;
+    readonly reason: TrustDenyReason;
+};
+/**
+ * Parse a raw `session_policy` JSON string into a {@link SessionPolicy}, failing
+ * CLOSED (to `block`) on any malformed input.
+ *
+ * SECURITY: a corrupt/unparseable policy must NEVER silently widen access — it
+ * resolves to `{ mode: 'block' }` so the gate denies and no decrypt occurs.
+ *
+ * @param raw - The `agent_service_grants.session_policy` column value.
+ * @returns A well-formed {@link SessionPolicy}; `block` on parse failure.
+ * @task T11937
+ */
+export declare function parseSessionPolicy(raw: string): SessionPolicy;
+/**
+ * Evaluate whether an agent may access a service connection — the **policy-
+ * before-decrypt** chokepoint.
+ *
+ * Pure: takes the agent's grants (already loaded) + the evaluation context and
+ * returns a {@link TrustDecision} WITHOUT touching crypto. The store calls
+ * `decryptGlobal` ONLY when the returned `allowed` is `true`. Deny order:
+ *
+ *  1. no matching grant → `no-grant` (denied).
+ *  2. grant policy `mode: 'block'` → `policy-block` (denied).
+ *  3. policy `manualApproval` set but context not `approved` →
+ *     `manual-approval-required` (denied).
+ *  4. otherwise → allowed (carrying any advisory `rateLimit`).
+ *
+ * @param grants - The agent's grant rows (the accessor loads these from
+ *   `agent_service_grants`). Only grants for `ctx.agentId` /
+ *   `ctx.serviceConnectionId` are considered.
+ * @param ctx - The evaluation context (agent, connection, approval flag).
+ * @returns The access decision. NEVER decrypts.
+ * @task T11937
+ */
+export declare function evaluateServiceAccess(grants: readonly ServiceGrant[], ctx: TrustEvalContext): TrustDecision;
+//# sourceMappingURL=service-trust-gate.d.ts.map

package/dist/store/service-trust-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-trust-gate.d.ts","sourceRoot":"","sources":["../../src/store/service-trust-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,cAAc,GAAG,0BAA0B,CAAC;AAEvF;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAElE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAkC7D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,GAAG,EAAE,gBAAgB,GACpB,aAAa,CAiBf"}

package/dist/store/service-trust-gate.js

@@ -0,0 +1,122 @@
+/**
+ * Service-vault trust gate — **policy-before-decrypt** per-agent access control.
+ *
+ * EP-UNIVERSAL-SERVICE-VAULT (epic T11765 · saga SG-VAULT-CORE T10409 · M2 W1a ·
+ * task T11937 · AC4). Ports onecli `connect.rs` selective-mode: an agent may use a
+ * service connection ONLY when (a) a row exists in `agent_service_grants` linking
+ * the agent to the connection, AND (b) the grant's `session_policy` evaluates to
+ * an allow. This module evaluates that decision from already-loaded grant data —
+ * it performs ZERO crypto. The store
+ * ({@link import('./service-connections-accessor.js')}) calls `decryptGlobal`
+ * ONLY after this gate returns `allowed: true`, so a denied/blocked agent NEVER
+ * triggers a decrypt (the policy-before-decrypt invariant, proven by unit test).
+ *
+ * ## Why the gate is decrypt-free
+ *
+ * The gate takes the grant rows as INPUT and returns a pure decision. It cannot
+ * decrypt even if it wanted to — it imports no crypto. The decryption chokepoint
+ * lives one layer up (the accessor), guarded by this decision. That separation is
+ * exactly what makes "a denied agent never decrypts" structurally true and
+ * spy-assertable: the spy is placed on `decryptGlobal`, and a deny path returns
+ * before the accessor reaches the decrypt call.
+ *
+ * ## Policy shape ({@link SessionPolicy})
+ *
+ * Mirrors onecli's `PolicyAction` (block / rate-limit / manual-approval) collapsed
+ * to a per-grant JSON:
+ *
+ *   - `mode: 'allow' | 'block'` — `block` is a hard deny (no decrypt).
+ *   - `rateLimit?` — advisory rate cap; the gate surfaces it but does not itself
+ *     count requests (the caller enforces). Presence alone does not deny.
+ *   - `manualApproval?: true` — the connection requires an out-of-band human
+ *     approval that has not been granted for this session → deny (no decrypt)
+ *     until the caller supplies `approved: true` in the evaluation context.
+ *
+ * A bare grant (`{"mode":"allow"}`, the column default) allows.
+ *
+ * @module store/service-trust-gate
+ * @task T11937
+ * @epic T11765
+ * @saga T10409
+ * @see ./service-connections-accessor.ts — the accessor that decrypts ONLY on allow
+ * @see ../../../onecli — `apps/gateway/src/connect.rs` selective-mode (the ported model)
+ */
+/**
+ * Parse a raw `session_policy` JSON string into a {@link SessionPolicy}, failing
+ * CLOSED (to `block`) on any malformed input.
+ *
+ * SECURITY: a corrupt/unparseable policy must NEVER silently widen access — it
+ * resolves to `{ mode: 'block' }` so the gate denies and no decrypt occurs.
+ *
+ * @param raw - The `agent_service_grants.session_policy` column value.
+ * @returns A well-formed {@link SessionPolicy}; `block` on parse failure.
+ * @task T11937
+ */
+export function parseSessionPolicy(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { mode: 'block' };
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return { mode: 'block' };
+    }
+    const obj = parsed;
+    const mode = obj['mode'] === 'block' ? 'block' : obj['mode'] === 'allow' ? 'allow' : 'block';
+    const policy = { mode };
+    if (obj['manualApproval'] === true) {
+        policy.manualApproval = true;
+    }
+    const rl = obj['rateLimit'];
+    if (typeof rl === 'object' && rl !== null) {
+        const rlObj = rl;
+        const maxRequests = rlObj['maxRequests'];
+        const window = rlObj['window'];
+        if (typeof maxRequests === 'number' &&
+            maxRequests > 0 &&
+            (window === 'minute' || window === 'hour' || window === 'day')) {
+            policy.rateLimit = { maxRequests, window };
+        }
+    }
+    return policy;
+}
+/**
+ * Evaluate whether an agent may access a service connection — the **policy-
+ * before-decrypt** chokepoint.
+ *
+ * Pure: takes the agent's grants (already loaded) + the evaluation context and
+ * returns a {@link TrustDecision} WITHOUT touching crypto. The store calls
+ * `decryptGlobal` ONLY when the returned `allowed` is `true`. Deny order:
+ *
+ *  1. no matching grant → `no-grant` (denied).
+ *  2. grant policy `mode: 'block'` → `policy-block` (denied).
+ *  3. policy `manualApproval` set but context not `approved` →
+ *     `manual-approval-required` (denied).
+ *  4. otherwise → allowed (carrying any advisory `rateLimit`).
+ *
+ * @param grants - The agent's grant rows (the accessor loads these from
+ *   `agent_service_grants`). Only grants for `ctx.agentId` /
+ *   `ctx.serviceConnectionId` are considered.
+ * @param ctx - The evaluation context (agent, connection, approval flag).
+ * @returns The access decision. NEVER decrypts.
+ * @task T11937
+ */
+export function evaluateServiceAccess(grants, ctx) {
+    const grant = grants.find((g) => g.agentId === ctx.agentId && g.serviceConnectionId === ctx.serviceConnectionId);
+    if (grant === undefined) {
+        return { allowed: false, reason: 'no-grant' };
+    }
+    const policy = grant.sessionPolicy;
+    if (policy.mode === 'block') {
+        return { allowed: false, reason: 'policy-block' };
+    }
+    if (policy.manualApproval === true && ctx.approved !== true) {
+        return { allowed: false, reason: 'manual-approval-required' };
+    }
+    return policy.rateLimit !== undefined
+        ? { allowed: true, rateLimit: policy.rateLimit }
+        : { allowed: true };
+}
+//# sourceMappingURL=service-trust-gate.js.map

package/dist/store/service-trust-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-trust-gate.js","sourceRoot":"","sources":["../../src/store/service-trust-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AA0FH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7F,MAAM,MAAM,GAIR,EAAE,IAAI,EAAE,CAAC;IACb,IAAI,GAAG,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE,CAAC;QACnC,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;IAC/B,CAAC;IACD,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;IAC5B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,EAA6B,CAAC;QAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,IACE,OAAO,WAAW,KAAK,QAAQ;YAC/B,WAAW,GAAG,CAAC;YACf,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,CAAC,EAC9D,CAAC;YACD,MAAM,CAAC,SAAS,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA+B,EAC/B,GAAqB;IAErB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CACvB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,mBAAmB,KAAK,GAAG,CAAC,mBAAmB,CACtF,CAAC;IACF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAChD,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IACnC,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,MAAM,CAAC,cAAc,KAAK,IAAI,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC,SAAS,KAAK,SAAS;QACnC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE;QAChD,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/store/validation-schemas.d.ts

@@ -227,10 +227,10 @@ export declare const brainLinkTypeSchema: z.ZodEnum<{
 }>;
 /** Zod enum schema for brain memory entity types. */
 export declare const brainMemoryTypeSchema: z.ZodEnum<{
+    observation: "observation";
     decision: "decision";
     pattern: "pattern";
     learning: "learning";
-    observation: "observation";
 }>;
 /** Zod enum schema for brain sticky note statuses. */
 export declare const brainStickyStatusSchema: z.ZodEnum<{
@@ -257,10 +257,10 @@ export declare const brainNodeTypeSchema: z.ZodEnum<{
     symbol: "symbol";
     file: "file";
     task: "task";
+    observation: "observation";
     decision: "decision";
     pattern: "pattern";
     learning: "learning";
-    observation: "observation";
     epic: "epic";
     session: "session";
     sticky: "sticky";
@@ -7969,7 +7969,7 @@ export declare const insertReleaseSchema: import("drizzle-orm/zod").BuildSchema<
         name: string;
         tableName: "tasks_releases";
         dataType: "string enum";
-        data: "latest" | "beta" | "dev" | "hotfix";
+        data: "beta" | "latest" | "dev" | "hotfix";
         driverParam: string;
         notNull: true;
         hasDefault: true;
@@ -8470,7 +8470,7 @@ export declare const selectReleaseSchema: import("drizzle-orm/zod").BuildSchema<
         name: string;
         tableName: "tasks_releases";
         dataType: "string enum";
-        data: "latest" | "beta" | "dev" | "hotfix";
+        data: "beta" | "latest" | "dev" | "hotfix";
         driverParam: string;
         notNull: true;
         hasDefault: true;

package/dist/tasks/agent-lifecycle-lane.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Pure agent-lifecycle LANE RESOLVER — the SINGLE source of truth for the
+ * seven dispatcher lanes shared by the Studio Kanban board and the `cleo tui`
+ * terminal cockpit.
+ *
+ * ## Why this lives in `@cleocode/core` (not Studio)
+ *
+ * The lane model was originally authored for the Studio read-only Kanban
+ * dispatcher (T11926) under
+ * `packages/studio/src/lib/components/tasks/agent-lifecycle-lane.ts`. The
+ * `cleo tui` Kanban home view (T11934) needs the EXACT same semantics — same
+ * seven lanes, same precedence ladder — so the model was lifted here, into the
+ * SDK package both surfaces already depend on, and the Studio copy is now a
+ * thin re-export of this module (relate T11934 ↔ T11926). One lane model, two
+ * renderers, zero divergence.
+ *
+ * It is intentionally a pure, framework-free `.ts` module: NO Svelte import, NO
+ * gateway/DB access, only a `TaskStatus` type from `@cleocode/contracts`. That
+ * keeps it trivially unit-testable under vitest's `environment: 'node'` and
+ * importable from any surface (CLI, TUI, Studio loader/route).
+ *
+ * The resolver answers *"where is this task in the agent dispatch lifecycle?"* —
+ * collapsing several orthogonal signals (status, verification gates,
+ * completion-readiness, blocking dependencies, HITL pauses, and any
+ * active-worker / orchestrate-ready hint) onto ONE of seven dispatcher lanes:
+ *
+ * ```
+ * Backlog → Ready → Running → Review → Blocked → Done → Cancelled
+ * ```
+ *
+ * @task T11934 — extracted to core as the shared lane SSoT
+ * @task T11926 — original Studio resolver (now re-exports this module)
+ * @epic T11916
+ */
+import type { TaskStatus } from '@cleocode/contracts';
+/**
+ * The seven dispatcher lanes, in canonical left-to-right board order.
+ *
+ * - `backlog`   — pending work not yet eligible to start (deps unmet OR no
+ *                 active dispatch signal).
+ * - `ready`     — dependencies satisfied and the task is eligible to be
+ *                 spawned, but no worker has claimed it yet.
+ * - `running`   — an agent/worker is actively executing (spawned / claimed).
+ * - `review`    — implementation done, awaiting verification gates / a PR
+ *                 merge before completion.
+ * - `blocked`   — held by an explicit `blockedBy` reason, an unmet dependency
+ *                 it cannot start without, or a HITL approval pause.
+ * - `done`      — terminal success.
+ * - `cancelled` — terminal abandonment.
+ */
+export type AgentLifecycleLane = 'backlog' | 'ready' | 'running' | 'review' | 'blocked' | 'done' | 'cancelled';
+/**
+ * Canonical ordered list of dispatcher lanes — drives column order on the
+ * board. Tasks in unknown / non-surfaced statuses (e.g. `archived`,
+ * `proposed`) are filtered before resolution and never appear.
+ */
+export declare const AGENT_LIFECYCLE_LANES: readonly AgentLifecycleLane[];
+/** Human-readable, board-facing labels for each lane. */
+export declare const AGENT_LIFECYCLE_LANE_LABELS: Readonly<Record<AgentLifecycleLane, string>>;
+/** One-line lane descriptions used for board empty-states + tooltips. */
+export declare const AGENT_LIFECYCLE_LANE_HINTS: Readonly<Record<AgentLifecycleLane, string>>;
+/**
+ * Minimal verification-gate snapshot the resolver consults to decide the
+ * {@link AgentLifecycleLane | review} lane.
+ *
+ * Structurally compatible with `TaskViewGatesStatus` from
+ * `@cleocode/contracts` so callers can pass the `/api/tasks` `views[i].
+ * gatesStatus` (Studio) or the gateway SDK's `view.gatesStatus` (TUI) straight
+ * through.
+ */
+export interface LaneGatesSnapshot {
+    /** Whether the `implemented` gate has passed. */
+    implemented: boolean;
+    /** Whether the `testsPassed` gate has passed. */
+    testsPassed: boolean;
+    /** Whether the `qaPassed` gate has passed. */
+    qaPassed: boolean;
+}
+/**
+ * Normalised, framework-free signal bundle for one task.
+ *
+ * Every caller projects a `Task` + its canonical `TaskView` (and the raw
+ * `depends` / `blockedBy` fields) onto this shape so the resolver never has to
+ * know about either contract directly — keeping it a pure, trivially testable
+ * function.
+ */
+export interface AgentLifecycleSignal {
+    /** Canonical execution status (`tasks.status`). */
+    status: TaskStatus;
+    /**
+     * Free-text blocker reason from `tasks.blockedBy`. Non-empty ⇒ the task is
+     * explicitly blocked by an operator/agent note (e.g. "waiting for API key",
+     * "awaiting HITL approval").
+     */
+    blockedBy?: string | null;
+    /**
+     * IDs of tasks this task depends on (`tasks.depends`). Combined with
+     * {@link AgentLifecycleSignal.unmetDependsCount} to decide Ready-vs-Backlog
+     * and dependency blocking.
+     */
+    depends?: readonly string[] | null;
+    /**
+     * Count of {@link AgentLifecycleSignal.depends} whose status is NOT `done`.
+     * `0` means every dependency is satisfied. When unknown (loader could not
+     * resolve), pass `undefined` — the resolver then treats a non-empty
+     * `depends` list as "not yet eligible" (conservative: keeps it in Backlog
+     * rather than falsely promoting to Ready).
+     */
+    unmetDependsCount?: number;
+    /**
+     * Verification gate snapshot. When all three gates are green and the task
+     * has not yet reached a terminal status, the task is parked in `review`
+     * awaiting completion.
+     */
+    gates?: LaneGatesSnapshot | null;
+    /**
+     * Canonical `readyToComplete` flag from `TaskView` — true when required
+     * gates are green AND no unresolved blocking deps AND status is non-terminal.
+     * A strong `review` signal.
+     */
+    readyToComplete?: boolean;
+    /**
+     * Whether a PR is open/awaiting for this task (review signal). The loader
+     * derives this from orchestration metadata when available; defaults to
+     * `false`.
+     */
+    prAwaiting?: boolean;
+    /**
+     * Whether the task is paused on a HITL (human-in-the-loop) approval gate.
+     * A `blocked` signal that outranks everything except terminal status.
+     */
+    hitlPending?: boolean;
+    /**
+     * Whether an agent/worker is actively spawned or has claimed this task.
+     * The loader derives this from the active-session / orchestrate signal in
+     * the existing data layer; defaults to `false`.
+     */
+    workerActive?: boolean;
+    /**
+     * Canonical `nextAction` hint from `TaskView`. `'spawn-worker'` is treated
+     * as an orchestrate-ready signal; `'blocked-on-deps'` reinforces blocking.
+     * Optional — the resolver never requires it.
+     */
+    nextAction?: string;
+}
+/**
+ * Resolve a single task's signal bundle onto exactly ONE
+ * {@link AgentLifecycleLane}.
+ *
+ * ## Precedence ladder (highest wins)
+ *
+ * 1. **`cancelled`** — terminal. `status === 'cancelled'`.
+ * 2. **`done`** — terminal. `status === 'done'`.
+ * 3. **`blocked`** — `status === 'blocked'` OR a non-empty `blockedBy` reason
+ *    OR a pending HITL gate OR a known-unmet dependency. (Blocked outranks
+ *    Running/Review/Ready because a blocked task cannot progress regardless of
+ *    other signals.)
+ * 4. **`review`** — non-terminal, not blocked, and verified: all gates green
+ *    OR `readyToComplete` OR a PR is awaiting. (A task in review may also be
+ *    `active`, but review outranks running — it is past execution.)
+ * 5. **`running`** — a worker is actively executing: `workerActive` OR
+ *    `status === 'active'` OR `nextAction === 'spawn-worker'`-already-spawned.
+ * 6. **`ready`** — `status === 'pending'`, dependencies satisfied, and an
+ *    orchestrate-ready hint (`nextAction === 'spawn-worker'`).
+ * 7. **`backlog`** — everything else (pending, not yet eligible / unwaved).
+ *
+ * The ladder is documented as `cancelled > done > blocked > review > running
+ * > ready > backlog`. Terminal lanes short-circuit first so a `done` task
+ * with stale gate/worker flags can never leak into Running or Review.
+ *
+ * @param signal - Normalised signal bundle (see {@link AgentLifecycleSignal}).
+ * @returns The single lane this task belongs in.
+ */
+export declare function resolveAgentLifecycleLane(signal: AgentLifecycleSignal): AgentLifecycleLane;
+//# sourceMappingURL=agent-lifecycle-lane.d.ts.map

package/dist/tasks/agent-lifecycle-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-lifecycle-lane.d.ts","sourceRoot":"","sources":["../../src/tasks/agent-lifecycle-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,GACN,WAAW,CAAC;AAEhB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAQrD,CAAC;AAEX,yDAAyD;AACzD,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAQ3E,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAQ1E,CAAC;AAMX;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,GAAG,kBAAkB,CA0C1F"}