@cleocode/core 2026.9.22 → 2026.9.24

package/dist/sessions/focus-state-store.d.ts

@@ -5,13 +5,14 @@
  * nextAction, …). Historically it lived under ONE global meta key
  * (`focus_state`) shared by every agent — so two concurrent agents writing
  * their current task clobbered each other. This module keys it per resolved
- * session id (`focus_state:<sessionId>`), with a backward-compatible read
- * fallback to the legacy global key so no data is lost on upgrade.
+ * session id (`focus_state:<sessionId>`). The legacy global key remains the
+ * focus of an UNBOUND caller only (T12501).
  *
  * Single source of truth: every read/write callsite across engine-ops,
  * briefing, drift-watchdog, session-drift, session-switch, and orchestrate/pivot
- * routes through {@link readFocusState} / {@link writeFocusState} so the keying
- * + fallback precedence is never duplicated.
+ * routes through {@link readFocusState} / {@link writeFocusState}, and every
+ * caller picks its session through {@link resolveFocusSessionId}, so the
+ * keying is never duplicated (T12501).
  *
  * @task T11345
  * @epic T11284
@@ -20,10 +21,17 @@ import type { TaskWorkState } from '@cleocode/contracts';
 /**
  * The legacy global focus_state meta key, shared by all agents before T11345.
  *
- * Retained as the read-fallback target so sessions that wrote focus_state
- * before this change (and the global-scope/no-session case) keep resolving.
+ * UNBOUND CALLERS ONLY (T12501): it is the focus of a caller that is bound to
+ * no session — {@link resolveFocusSessionId} returned `null`. A caller bound
+ * to a session never reads or writes it: its focus lives only under
+ * `focus_state:<sessionId>`. The exceptions only ever CLEAR its pointer: a
+ * bound session with no key yet adopts a live legacy pointer once on upgrade
+ * ({@link readFocusState}), a bound `cleo stop` releases it
+ * ({@link releaseLegacyPointer}), and {@link clearFocusForFinishedTask} clears
+ * a pointer to a finished task wherever it is.
  *
  * @task T11345
+ * @task T12501
  */
 export declare const LEGACY_FOCUS_STATE_KEY: "focus_state";
 /**
@@ -47,11 +55,40 @@ export interface FocusStateMetaAccessor {
     }) => Promise<T>): Promise<T>;
 }
 /**
- * Compute the focus_state meta key for a resolved session id.
+ * THE focus-key rule (T12501): the session whose focus key the CALLER reads
+ * and writes. Every focus reader and writer — start, stop, pivot, complete's
+ * clear, `cleo current`, session status, briefing, inject, bootstrap, stats,
+ * validation, attention and orchestrator startup — resolves through this one
+ * function, so a write and the read that follows it can never land on
+ * different keys.
+ *
+ * It is the mutation resolver (`resolveBoundSessionId` in `store/session-store.ts`): the daemon
+ * connection handle, then an env-named session whose row exists, then the
+ * session this terminal started or resumed. It never guesses the newest
+ * active row — from an unbound terminal that is another agent's session, and
+ * its focus is not this caller's.
+ *
+ * `null` means the caller is bound to no session (or the session store
+ * cannot be opened); {@link focusStateKey} then maps it to the legacy global
+ * key (unbound callers only).
+ *
+ * @param cwd - Project root for session resolution.
+ * @returns The bound session id, or `null` when the caller is unbound.
+ * @example
+ * ```ts
+ * const focus = await readLiveFocus(acc, await resolveFocusSessionId(projectRoot));
+ * ```
+ * @task T12501
+ */
+export declare function resolveFocusSessionId(cwd?: string): Promise<string | null>;
+/**
+ * Compute the focus_state meta key for a session id from
+ * {@link resolveFocusSessionId} (or an explicitly named session).
  *
  * - A non-empty session id → the per-session key `focus_state:<sessionId>`.
- * - `null` / `undefined` (no resolvable session, e.g. global-scope CLI call) →
- *   the legacy global key so behaviour is unchanged when there is no session.
+ * - `null` / `undefined` (the caller is bound to no session) → the legacy
+ *   global key, {@link LEGACY_FOCUS_STATE_KEY}. Only an unbound caller lands
+ *   here (T12501).
  *
  * @param sessionId - Resolved session id, or `null` when none.
  * @returns The meta key to read/write.
@@ -59,31 +96,69 @@ export interface FocusStateMetaAccessor {
  */
 export declare function focusStateKey(sessionId: string | null | undefined): string;
 /**
- * Read the RAW focus_state blob for a resolved session id (per-session,
- * env-aware) — for read-modify-write only. Anything that reports or acts on
- * the current task reads {@link readLiveFocus}, which never returns a
- * finished task (T12684).
+ * The focus session id for a caller already resolved by the read resolver
+ * (`resolveSessionForRead`): its own session when bound, `null` when the row
+ * is only the newest active one. Equal to {@link resolveFocusSessionId} — the
+ * read resolver tries the same bound tiers first — so a surface that needs
+ * both the session row and the focus key resolves once (T12501).
+ *
+ * @param read - The read resolution: the session and its `unbound` label.
+ * @returns The bound session id, or `null` for an unbound caller.
+ * @example
+ * ```ts
+ * const read = await resolveSessionForRead(root);
+ * const focus = await readLiveFocus(acc, focusSessionIdFromRead(read));
+ * ```
+ * @task T12501
+ */
+export declare function focusSessionIdFromRead(read: {
+    readonly session: {
+        readonly id: string;
+    } | null;
+    readonly unbound: boolean;
+}): string | null;
+/**
+ * Read the RAW focus_state blob for a session id — for read-modify-write
+ * only. Anything that reports or acts on the current task reads
+ * {@link readLiveFocus}, which never returns a finished task (T12684).
  *
- * Resolution:
- * 1. Read the per-session key `focus_state:<sessionId>`.
- * 2. If absent AND a session id was provided, fall back to the legacy global
- *    `focus_state` key (backward-compat — sessions written before T11345).
+ * Reads {@link focusStateKey}. The legacy global key is an unbound caller's
+ * focus, never read as a bound session's — except once, on upgrade: when the
+ * session's key is ABSENT (not merely `currentTask: null`) and the legacy key
+ * holds a live pointer, the session adopts it and the legacy pointer is
+ * cleared, so no second session can adopt it too (T12501).
  *
  * @param accessor  - Metadata accessor.
- * @param sessionId - Resolved session id (or `null` for the global key).
- * @returns The focus_state blob, or `null` when neither key has a value.
+ * @param sessionId - Session id from {@link resolveFocusSessionId}, or `null`
+ *   for an unbound caller (the legacy key).
+ * @returns The focus_state blob, or `null` when there is none.
  * @task T11345
+ * @task T12501
  */
 export declare function readFocusState(accessor: FocusStateMetaAccessor, sessionId: string | null | undefined): Promise<TaskWorkState | null>;
 /**
- * Write the focus_state blob for a resolved session id (per-session).
+ * Clear the legacy global pointer when it names `taskId` — for a BOUND
+ * caller's `cleo stop`, so a pre-upgrade pointer to the task it stopped is not
+ * left behind for unbound callers (T12501). Compare-and-set on the pointer.
+ *
+ * @param accessor - Metadata accessor.
+ * @param taskId - The task being stopped.
+ * @returns `true` when the legacy pointer was cleared.
+ * @task T12501
+ */
+export declare function releaseLegacyPointer(accessor: FocusStateMetaAccessor, taskId: string): Promise<boolean>;
+/**
+ * Write the focus_state blob for a session id.
  *
- * Always writes the per-session key so concurrent agents never clobber each
- * other. The legacy global key is left untouched (read-only fallback) to avoid
- * resurrecting the shared-write contention this module exists to eliminate.
+ * A bound session writes only its own key, so concurrent sessions never
+ * clobber each other; only an unbound caller (`sessionId` null) writes the
+ * legacy key. (A bound session touches the legacy key only to clear a pointer:
+ * adoption on upgrade, {@link releaseLegacyPointer} and
+ * {@link clearFocusForFinishedTask}.) (T12501)
  *
  * @param accessor  - Metadata accessor.
- * @param sessionId - Resolved session id (or `null` for the global key).
+ * @param sessionId - Session id from {@link resolveFocusSessionId}, or `null`
+ *   for an unbound caller (the legacy key).
  * @param value     - The focus_state blob to persist.
  * @task T11345
  */
@@ -98,7 +173,8 @@ export declare function writeFocusState(accessor: FocusStateMetaAccessor, sessio
  *
  * @param accessor   - Metadata accessor.
  * @param sessionIds - Session ids whose scoped key may hold the pointer
- *   (the bound session, the env session); duplicates and nulls are ignored.
+ *   (the caller's {@link resolveFocusSessionId}); duplicates and nulls are
+ *   ignored.
  * @param taskId     - The completed task.
  * @returns The meta keys that were cleared (empty when none pointed at it).
  * @task T12660
@@ -160,9 +236,15 @@ export interface LiveFocus {
  * read reports it stale.
  *
  * @param accessor - Metadata accessor with a live task lookup.
- * @param sessionId - Resolved session id (or `null` for the global key).
+ * @param sessionId - Session id from {@link resolveFocusSessionId}, or `null`
+ *   for an unbound caller (the legacy key).
+ * @param known - Tasks the caller already loaded (e.g. the briefing's task
+ *   map): a pointer found there skips the extra lookup (T12698). A pointer
+ *   absent from it (archived tasks are not listed) is still looked up.
  * @returns The blob, the live current task, and the stale pointer if any.
  * @task T12684
  */
-export declare function readLiveFocus(accessor: LiveFocusAccessor, sessionId: string | null | undefined): Promise<LiveFocus>;
+export declare function readLiveFocus(accessor: LiveFocusAccessor, sessionId: string | null | undefined, known?: ReadonlyMap<string, {
+    status: string;
+}>): Promise<LiveFocus>;
 //# sourceMappingURL=focus-state-store.d.ts.map

package/dist/sessions/focus-state-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"focus-state-store.d.ts","sourceRoot":"","sources":["../../src/sessions/focus-state-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAG,aAAsB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;OAIG;IACH,WAAW,CAAC,CAAC,CAAC,EACZ,EAAE,EAAE,CAAC,EAAE,EAAE;QAAE,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GACnF,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAY/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,sBAAsB,EAChC,UAAU,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EACpD,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBnB;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,iBAAiB,GAAG,IAAI,CAK1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GACzC,MAAM,CAOR;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,8EAA8E;IAC9E,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACpE;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,8EAA8E;IAC9E,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,OAAO,CAAC,SAAS,CAAC,CAMpB"}
+{"version":3,"file":"focus-state-store.d.ts","sourceRoot":"","sources":["../../src/sessions/focus-state-store.ts"],"names":[],"mappings":"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"}

package/dist/sessions/focus-state-store.js

@@ -5,13 +5,14 @@
  * nextAction, …). Historically it lived under ONE global meta key
  * (`focus_state`) shared by every agent — so two concurrent agents writing
  * their current task clobbered each other. This module keys it per resolved
- * session id (`focus_state:<sessionId>`), with a backward-compatible read
- * fallback to the legacy global key so no data is lost on upgrade.
+ * session id (`focus_state:<sessionId>`). The legacy global key remains the
+ * focus of an UNBOUND caller only (T12501).
  *
  * Single source of truth: every read/write callsite across engine-ops,
  * briefing, drift-watchdog, session-drift, session-switch, and orchestrate/pivot
- * routes through {@link readFocusState} / {@link writeFocusState} so the keying
- * + fallback precedence is never duplicated.
+ * routes through {@link readFocusState} / {@link writeFocusState}, and every
+ * caller picks its session through {@link resolveFocusSessionId}, so the
+ * keying is never duplicated (T12501).
  *
  * @task T11345
  * @epic T11284
@@ -20,18 +21,65 @@ import { TERMINAL_TASK_STATUSES } from '@cleocode/contracts';
 /**
  * The legacy global focus_state meta key, shared by all agents before T11345.
  *
- * Retained as the read-fallback target so sessions that wrote focus_state
- * before this change (and the global-scope/no-session case) keep resolving.
+ * UNBOUND CALLERS ONLY (T12501): it is the focus of a caller that is bound to
+ * no session — {@link resolveFocusSessionId} returned `null`. A caller bound
+ * to a session never reads or writes it: its focus lives only under
+ * `focus_state:<sessionId>`. The exceptions only ever CLEAR its pointer: a
+ * bound session with no key yet adopts a live legacy pointer once on upgrade
+ * ({@link readFocusState}), a bound `cleo stop` releases it
+ * ({@link releaseLegacyPointer}), and {@link clearFocusForFinishedTask} clears
+ * a pointer to a finished task wherever it is.
  *
  * @task T11345
+ * @task T12501
  */
 export const LEGACY_FOCUS_STATE_KEY = 'focus_state';
 /**
- * Compute the focus_state meta key for a resolved session id.
+ * THE focus-key rule (T12501): the session whose focus key the CALLER reads
+ * and writes. Every focus reader and writer — start, stop, pivot, complete's
+ * clear, `cleo current`, session status, briefing, inject, bootstrap, stats,
+ * validation, attention and orchestrator startup — resolves through this one
+ * function, so a write and the read that follows it can never land on
+ * different keys.
+ *
+ * It is the mutation resolver (`resolveBoundSessionId` in `store/session-store.ts`): the daemon
+ * connection handle, then an env-named session whose row exists, then the
+ * session this terminal started or resumed. It never guesses the newest
+ * active row — from an unbound terminal that is another agent's session, and
+ * its focus is not this caller's.
+ *
+ * `null` means the caller is bound to no session (or the session store
+ * cannot be opened); {@link focusStateKey} then maps it to the legacy global
+ * key (unbound callers only).
+ *
+ * @param cwd - Project root for session resolution.
+ * @returns The bound session id, or `null` when the caller is unbound.
+ * @example
+ * ```ts
+ * const focus = await readLiveFocus(acc, await resolveFocusSessionId(projectRoot));
+ * ```
+ * @task T12501
+ */
+export async function resolveFocusSessionId(cwd) {
+    // Dynamic: the store module is heavy and this module is imported widely.
+    const { resolveBoundSessionId } = await import('../store/session-store.js');
+    try {
+        return await resolveBoundSessionId(cwd);
+    }
+    catch {
+        // No readable session store means no session can be bound: the caller is
+        // unbound, exactly as before any session existed.
+        return null;
+    }
+}
+/**
+ * Compute the focus_state meta key for a session id from
+ * {@link resolveFocusSessionId} (or an explicitly named session).
  *
  * - A non-empty session id → the per-session key `focus_state:<sessionId>`.
- * - `null` / `undefined` (no resolvable session, e.g. global-scope CLI call) →
- *   the legacy global key so behaviour is unchanged when there is no session.
+ * - `null` / `undefined` (the caller is bound to no session) → the legacy
+ *   global key, {@link LEGACY_FOCUS_STATE_KEY}. Only an unbound caller lands
+ *   here (T12501).
  *
  * @param sessionId - Resolved session id, or `null` when none.
  * @returns The meta key to read/write.
@@ -41,43 +89,122 @@ export function focusStateKey(sessionId) {
     return sessionId ? `${LEGACY_FOCUS_STATE_KEY}:${sessionId}` : LEGACY_FOCUS_STATE_KEY;
 }
 /**
- * Read the RAW focus_state blob for a resolved session id (per-session,
- * env-aware) — for read-modify-write only. Anything that reports or acts on
- * the current task reads {@link readLiveFocus}, which never returns a
- * finished task (T12684).
+ * The focus session id for a caller already resolved by the read resolver
+ * (`resolveSessionForRead`): its own session when bound, `null` when the row
+ * is only the newest active one. Equal to {@link resolveFocusSessionId} — the
+ * read resolver tries the same bound tiers first — so a surface that needs
+ * both the session row and the focus key resolves once (T12501).
+ *
+ * @param read - The read resolution: the session and its `unbound` label.
+ * @returns The bound session id, or `null` for an unbound caller.
+ * @example
+ * ```ts
+ * const read = await resolveSessionForRead(root);
+ * const focus = await readLiveFocus(acc, focusSessionIdFromRead(read));
+ * ```
+ * @task T12501
+ */
+export function focusSessionIdFromRead(read) {
+    return read.unbound ? null : (read.session?.id ?? null);
+}
+/** Whether the accessor can look a task up (a {@link LiveFocusAccessor}). */
+function hasTaskLookup(accessor) {
+    return 'loadSingleTask' in accessor;
+}
+/**
+ * Upgrade path (T12501): a bound session with no focus key yet adopts the
+ * pre-upgrade focus held in the legacy global key — once.
  *
- * Resolution:
- * 1. Read the per-session key `focus_state:<sessionId>`.
- * 2. If absent AND a session id was provided, fall back to the legacy global
- *    `focus_state` key (backward-compat — sessions written before T11345).
+ * Only a live pointer is adopted (a done, cancelled, archived or missing task
+ * is not). The blob is copied to the session key and the legacy pointer is
+ * cleared with a compare-and-set on that pointer, inside one transaction when
+ * the store offers one, so exactly one bound session can adopt it.
+ *
+ * @returns The adopted (or concurrently written) blob, or `null`.
+ */
+async function adoptLegacyFocus(accessor, sessionId) {
+    if (!hasTaskLookup(accessor))
+        return null;
+    const legacy = await accessor.getMetaValue(LEGACY_FOCUS_STATE_KEY);
+    const pointer = legacy?.currentTask ?? null;
+    if (!pointer)
+        return null;
+    if (staleFocusPointer(pointer, (await accessor.loadSingleTask(pointer))?.status))
+        return null;
+    const key = focusStateKey(sessionId);
+    const adopt = async (set) => {
+        const own = await accessor.getMetaValue(key);
+        if (own)
+            return own; // written meanwhile — the session's own focus wins
+        const now = await accessor.getMetaValue(LEGACY_FOCUS_STATE_KEY);
+        if (!now || now.currentTask !== pointer)
+            return null; // another session adopted it
+        await set(key, now);
+        await set(LEGACY_FOCUS_STATE_KEY, { ...now, currentTask: null });
+        return now;
+    };
+    return accessor.transaction
+        ? accessor.transaction((tx) => adopt((k, v) => tx.setMetaValue(k, v)))
+        : adopt((k, v) => accessor.setMetaValue(k, v));
+}
+/**
+ * Read the RAW focus_state blob for a session id — for read-modify-write
+ * only. Anything that reports or acts on the current task reads
+ * {@link readLiveFocus}, which never returns a finished task (T12684).
+ *
+ * Reads {@link focusStateKey}. The legacy global key is an unbound caller's
+ * focus, never read as a bound session's — except once, on upgrade: when the
+ * session's key is ABSENT (not merely `currentTask: null`) and the legacy key
+ * holds a live pointer, the session adopts it and the legacy pointer is
+ * cleared, so no second session can adopt it too (T12501).
  *
  * @param accessor  - Metadata accessor.
- * @param sessionId - Resolved session id (or `null` for the global key).
- * @returns The focus_state blob, or `null` when neither key has a value.
+ * @param sessionId - Session id from {@link resolveFocusSessionId}, or `null`
+ *   for an unbound caller (the legacy key).
+ * @returns The focus_state blob, or `null` when there is none.
  * @task T11345
+ * @task T12501
  */
 export async function readFocusState(accessor, sessionId) {
-    const key = focusStateKey(sessionId);
-    const scoped = await accessor.getMetaValue(key);
-    if (scoped)
-        return scoped;
-    // Backward-compat: a session existed before T11345 keyed under the global
-    // key. Only fall back when we actually scoped to a session (else the scoped
-    // key IS the legacy key and we'd read it twice).
-    if (sessionId) {
-        return accessor.getMetaValue(LEGACY_FOCUS_STATE_KEY);
-    }
-    return null;
+    const own = await accessor.getMetaValue(focusStateKey(sessionId));
+    if (own || !sessionId)
+        return own;
+    return adoptLegacyFocus(accessor, sessionId);
+}
+/**
+ * Clear the legacy global pointer when it names `taskId` — for a BOUND
+ * caller's `cleo stop`, so a pre-upgrade pointer to the task it stopped is not
+ * left behind for unbound callers (T12501). Compare-and-set on the pointer.
+ *
+ * @param accessor - Metadata accessor.
+ * @param taskId - The task being stopped.
+ * @returns `true` when the legacy pointer was cleared.
+ * @task T12501
+ */
+export async function releaseLegacyPointer(accessor, taskId) {
+    const clear = async (set) => {
+        const legacy = await accessor.getMetaValue(LEGACY_FOCUS_STATE_KEY);
+        if (legacy?.currentTask !== taskId)
+            return false;
+        await set(LEGACY_FOCUS_STATE_KEY, { ...legacy, currentTask: null });
+        return true;
+    };
+    return accessor.transaction
+        ? accessor.transaction((tx) => clear((k, v) => tx.setMetaValue(k, v)))
+        : clear((k, v) => accessor.setMetaValue(k, v));
 }
 /**
- * Write the focus_state blob for a resolved session id (per-session).
+ * Write the focus_state blob for a session id.
  *
- * Always writes the per-session key so concurrent agents never clobber each
- * other. The legacy global key is left untouched (read-only fallback) to avoid
- * resurrecting the shared-write contention this module exists to eliminate.
+ * A bound session writes only its own key, so concurrent sessions never
+ * clobber each other; only an unbound caller (`sessionId` null) writes the
+ * legacy key. (A bound session touches the legacy key only to clear a pointer:
+ * adoption on upgrade, {@link releaseLegacyPointer} and
+ * {@link clearFocusForFinishedTask}.) (T12501)
  *
  * @param accessor  - Metadata accessor.
- * @param sessionId - Resolved session id (or `null` for the global key).
+ * @param sessionId - Session id from {@link resolveFocusSessionId}, or `null`
+ *   for an unbound caller (the legacy key).
  * @param value     - The focus_state blob to persist.
  * @task T11345
  */
@@ -94,7 +221,8 @@ export async function writeFocusState(accessor, sessionId, value) {
  *
  * @param accessor   - Metadata accessor.
  * @param sessionIds - Session ids whose scoped key may hold the pointer
- *   (the bound session, the env session); duplicates and nulls are ignored.
+ *   (the caller's {@link resolveFocusSessionId}); duplicates and nulls are
+ *   ignored.
  * @param taskId     - The completed task.
  * @returns The meta keys that were cleared (empty when none pointed at it).
  * @task T12660
@@ -164,16 +292,20 @@ export function staleFocusWarning(stale, next) {
  * read reports it stale.
  *
  * @param accessor - Metadata accessor with a live task lookup.
- * @param sessionId - Resolved session id (or `null` for the global key).
+ * @param sessionId - Session id from {@link resolveFocusSessionId}, or `null`
+ *   for an unbound caller (the legacy key).
+ * @param known - Tasks the caller already loaded (e.g. the briefing's task
+ *   map): a pointer found there skips the extra lookup (T12698). A pointer
+ *   absent from it (archived tasks are not listed) is still looked up.
  * @returns The blob, the live current task, and the stale pointer if any.
  * @task T12684
  */
-export async function readLiveFocus(accessor, sessionId) {
+export async function readLiveFocus(accessor, sessionId, known) {
     const state = await readFocusState(accessor, sessionId);
     const pointer = state?.currentTask ?? null;
     if (!pointer)
         return { state, currentTask: null, staleFocus: null };
-    const staleFocus = staleFocusPointer(pointer, (await accessor.loadSingleTask(pointer))?.status);
+    const staleFocus = staleFocusPointer(pointer, (known?.get(pointer) ?? (await accessor.loadSingleTask(pointer)))?.status);
     return { state, currentTask: staleFocus ? null : pointer, staleFocus };
 }
 //# sourceMappingURL=focus-state-store.js.map

package/dist/sessions/focus-state-store.js.map

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

package/dist/sessions/handoff.d.ts.map

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

package/dist/sessions/handoff.js

@@ -19,6 +19,8 @@ import { CleoError } from '../errors.js';
 import { assessKnowledgeCoverage } from '../nexus/knowledge.js';
 import { getTaskAccessor } from '../store/data-accessor.js';
 import { insertHandoffEntry } from '../store/session-store.js';
+import { rankTasks } from '../task-tools/score-task-priority.js';
+import { loadRankingContext } from '../tasks/task-next.js';
 import { getDecisionLog } from './decisions.js';
 const execFileAsync = promisify(execFile);
 /**
@@ -45,7 +47,7 @@ export async function computeHandoff(projectRoot, options) {
         tasksCompleted: session.tasksCompleted ?? [],
         tasksCreated: session.tasksCreated ?? [],
         decisionsRecorded: decisions.length,
-        nextSuggested: computeNextSuggested(session, tasks),
+        nextSuggested: computeNextSuggested(session, tasks, (await loadRankingContext(accessor, tasks)).ctx),
         openBlockers: findOpenBlockers(tasks, session),
         openBugs: findOpenBugs(tasks, session),
         // GH #1277 — emitted unconditionally. `null` is a recorded answer; an
@@ -59,10 +61,10 @@ export async function computeHandoff(projectRoot, options) {
     return handoff;
 }
 /**
- * Compute top-3 next suggested tasks.
- * Prioritizes uncompleted tasks within the session scope.
+ * Compute top-3 next suggested tasks: uncompleted tasks within the session
+ * scope, in THE comparator's order (D11161, T12692).
  */
-function computeNextSuggested(session, tasks) {
+function computeNextSuggested(session, tasks, ranking) {
     // Filter to tasks in scope
     const scopeTaskIds = getScopeTaskIds(session, tasks);
     // Get uncompleted tasks in scope
@@ -70,21 +72,10 @@ function computeNextSuggested(session, tasks) {
         t.status !== 'done' &&
         t.status !== 'archived' &&
         t.status !== 'cancelled');
-    // Sort by priority and created date
-    const priorityOrder = {
-        critical: 0,
-        high: 1,
-        medium: 2,
-        low: 3,
-    };
-    pendingTasks.sort((a, b) => {
-        const priorityDiff = (priorityOrder[a.priority ?? 'medium'] ?? 99) - (priorityOrder[b.priority ?? 'medium'] ?? 99);
-        if (priorityDiff !== 0)
-            return priorityDiff;
-        return (a.createdAt ?? '').localeCompare(b.createdAt ?? '');
-    });
+    // T12692: THE comparator (D11161) — band, severity, tiebreak, createdAt, id.
+    const ranked = rankTasks(pendingTasks, ranking).map((r) => r.task);
     // Take top 3
-    return pendingTasks.slice(0, 3).map((t) => t.id);
+    return ranked.slice(0, 3).map((t) => t.id);
 }
 /**
  * Find tasks with blockers in the session scope.