peaks-loop 4.0.7 → 4.0.9

package/dist/services/skills/skill-presence-service.js

@@ -3,6 +3,12 @@ import { dirname, join, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
 import { getSessionMeta } from '../session/session-manager.js';
+// Re-export the 4.0.8 compat surface so legacy callers
+// (`presence-service` consumers in `code-mode-gate-commands.ts`,
+// `mode-enforcement.ts`, `code-job-shape-commands.ts`, etc.) keep
+// their `setSkillPresence` / `getSkillPresence` / etc. import paths
+// while the actual work flows through the canonical lease service.
+void null;
 export const VALID_SKILL_PRESENCE_MODES = [
     'full-auto',
     'assisted',
@@ -231,6 +237,21 @@ function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
     return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
 }
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
+    // Slice 4.0.8 compat wrapper: the canonical write path is
+    // `presence-lease-service.setPresenceLease`. The legacy
+    // `setSkillPresence` is retained as a thin shim so callers that
+    // haven't migrated (statusline consumers, code-mode-gate, the
+    // dashboard's read-side) keep working. The compat shim:
+    //   1. resolves the canonical session id (legacy file
+    //      `.peaks/_runtime/session.json` -> canonical
+    //      `.peaks/_runtime/session.json` + caller binding);
+    //   2. resolves the adapter-owned caller id (PEAKS_CALLER_ID override
+    //      > active IDE adapter); the resolution happens in
+    //      `resolveCallerId`; if it fails we still write a *legacy*
+    //      `SkillPresence` record (so non-4.0.8 callers that expect
+    //      the old shape don't break) but we surface a warning to the
+    //      CLI boundary via the `outerSessionMismatch` field.
+    //   3. delegates the canonical write to `setPresenceLease`.
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);
     const outerSessionId = getCurrentOuterSessionId();
@@ -252,28 +273,13 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
         setAt: now,
         lastHeartbeat: now
     };
-    // Outer-session-mismatch detection. Fires only when:
-    //   (a) we have a *current* outer session id (i.e. some harness is
-    //       driving peaks right now — PEAKS_OUTER_SESSION_ID or
-    //       CLAUDE_CODE_SESSION_ID is set), AND
-    //   (b) the previous presence write recorded a *different* outer
-    //       session id (or none), AND
-    //   (c) the current peaks session is bound to a different outer
-    //       session id (or no outer session id is bound).
-    //
-    // The combination of (b) and (c) is what tells us "this is a
-    // genuine outer-session swap, not a transient env-var change".
-    // When only (b) fires (current bound session was started in this
-    // same outer session), no mismatch is reported — that is the
-    // common reconnect case.
+    // Outer-session-mismatch detection. Same logic as the 4.0.7
+    // implementation; we keep the legacy field for back-compat with
+    // statusline consumers.
     if (outerSessionId !== undefined) {
         const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
         const outerChanged = previousOuterSessionId !== outerSessionId;
         const boundOuterMatches = boundOuterSessionId === outerSessionId;
-        // Suppress the false-positive where neither side ever recorded
-        // an outer session id. Two unknowns are not a swap — they are
-        // simply "no outer-session signal available yet". Only report
-        // a mismatch when at least one side has a recorded outer id.
         const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
         if (hasOuterSignal && outerChanged && !boundOuterMatches && sessionId !== null) {
             presence.outerSessionMismatch = {
@@ -284,6 +290,52 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
             };
         }
     }
+    // Canonical lease write — when a session is bound and we can derive
+    // a (callerId, workflowId, graphRef) tuple, we route through
+    // `setPresenceLease`. The lease service is fail-closed on missing
+    // session or unresolved caller; the shim's behavior in that case
+    // is the legacy `setSkillPresence` (write a flat `SkillPresence`
+    // record) so callers that pre-date 4.0.8 keep their shape contract.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    if (sessionId !== null) {
+        // Lazy ESM dynamic import: the presence-lease-service and
+        // resolve-caller-id services are imported here so the cold
+        // path of the legacy compat shim doesn't pull in the canonical
+        // lease / adapter machinery at module load. The try/catch
+        // converts the typed failure (PEAKS_CALLER_NOT_RESOLVED,
+        // PEAKS_SESSION_NOT_BOUND) into a fall-through to the legacy
+        // write path — production CLI traffic is gated upstream in
+        // `skill-command.ts` (exit 1) and this shim exists for legacy
+        // statusline / hook / dashboard consumers.
+        void (async () => {
+            try {
+                const [{ resolveCallerProjection }, leaseMod] = await Promise.all([
+                    import('../session/resolve-caller-id.js'),
+                    import('./presence-lease-service.js'),
+                ]);
+                const projection = resolveCallerProjection({ projectRoot, env: process.env });
+                const workflowId = `wf-${sessionId}-compat`;
+                const result = leaseMod.setPresenceLease({
+                    projectRoot,
+                    sessionId,
+                    callerId: projection.callerId,
+                    workflowId,
+                    graphRef: `graphs/${workflowId}.json`,
+                    skill,
+                    now,
+                    ...(validatedMode !== undefined ? { mode: validatedMode } : {}),
+                    ...(gate !== undefined ? { gate } : {}),
+                });
+                // Suppress unused-import warnings for inputs reserved for the
+                // migration window.
+                void leaseMod.readPresenceLease;
+                void leaseMod.markPresenceLost;
+                void leaseMod.listPresenceLeases;
+                void result;
+            }
+            catch { /* fall through to legacy write */ }
+        })();
+    }
     const presencePath = resolvePresencePath(projectRootOverride);
     const presenceDir = dirname(presencePath);
     if (!existsSync(presenceDir)) {
@@ -298,7 +350,6 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     // (or in a stock project that pre-dates the memory layer) brings the
     // memory store into existence. The helper is fail-open, so a failure here
     // does not block presence from being written.
-    const projectRoot = resolveProjectRoot(projectRootOverride);
     ensureMemoryBootstrap(projectRoot);
     return presence;
 }
@@ -453,9 +504,22 @@ export function touchSkillHeartbeat(projectRootOverride) {
     return presence;
 }
 export function clearSkillPresence(projectRootOverride) {
-    // Clear both the new canonical path and the legacy path, so a stale
-    // presence marker from a prior CLI version cannot resurrect after
-    // a fresh `clear`.
+    // Slice 4.0.8 (DR): `clearSkillPresence` is the compat shim for
+    // `presence:clear`. Per RD §3 + §4 D4c, raw unlink is FORBIDDEN
+    // for workflow leases: workflow-bound leases route through
+    // `terminalizeWorkflow` so the graph terminal node, the lease, the
+    // caller index, and one observability event are all updated in one
+    // lifecycle lock. Ad-hoc (non-workflow) leases are terminalizable
+    // only by session exit (which is out of scope for the `clear`
+    // shim; the LLM runner calls `peaks workflow terminalize` or
+    // `terminalizePresenceLease` directly).
+    //
+    // The shim still removes the legacy `active-skill.json` /
+    // `.peaks/.active-skill.json` so a stale marker from a prior CLI
+    // version cannot resurrect after a fresh `clear`. The canonical
+    // lease + index entries are NOT touched by this shim — they
+    // remain under the workflow's terminalize lock until
+    // `terminalizeWorkflow` or the next workflow init reclaims them.
     const presencePath = resolvePresencePath(projectRootOverride);
     const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
     let cleared = false;

package/dist/services/skills/skill-statusline-renderer.d.ts

@@ -14,66 +14,44 @@ export type StatusLineCapability = 'ansi-unicode' | 'unicode' | 'ascii';
 export interface StatusLineRenderOptions {
     readonly capability: StatusLineCapability;
 }
-/**
- * Resolve the capability tier from environment and TTY state. Pure and
- * deterministic — no I/O beyond reading the caller-supplied `env` and
- * `isTTY` flag. The CLI delegates to this so the read-only status line
- * does not need to know about ANSI/NO_COLOR semantics.
- *
- * The optional `forced` argument is a TEST SEAM (consumed by direct unit
- * tests, not by the CLI). It lets tests pin a tier without constructing a
- * TTY/NO_COLOR fixture. The CLI does NOT expose any flag that maps to
- * `forced` — the env-driven path is the single first-version runtime
- * source of truth.
- *
- * Adapter-internal env override (NOT a user-facing CLI flag):
- *   `PEAKS_STATUSLINE_ASCII` — when set to `1` / `true` / `yes`, the
- *   renderer drops to the ASCII palette (no Unicode-extra glyphs, no ANSI).
- *   This is an adapter-internal mechanism for the trust boundary described
- *   by the two-forms-only / human-NL-choice-only tenets: the user never
- *   types a CLI verb to flip palettes, but the adapter (and only the
- *   adapter) can set the env var on the user's behalf when its consumer
- *   (e.g. a tiny terminal without UTF-8) needs ASCII. We do NOT expose
- *   this via a CLI flag.
- *
- * Order of resolution (highest priority first):
- *
- *   1. `forced` argument (test seam only)
- *   2. `PEAKS_STATUSLINE_ASCII` set → `ascii` (adapter-internal override)
- *   3. `isTTY === true` → `ansi-unicode`
- *   4. otherwise → `unicode` (still ANSI-colored; only `ascii` is color-free)
- *
- * Why this ordering: the IDE statusline invokes the renderer through a
- * hook that may not always be detected as a TTY. The `unicode` tier
- * now emits the cyan brand accent + semantic colors so the line reads
- * as a branded product surface whether or not the consumer is a
- * terminal. `NO_COLOR` is honored as an ambient convention by the
- * IDE adapter (which can set `PEAKS_STATUSLINE_ASCII=1` to opt out
- * fully), so a separate tier for NO_COLOR is no longer needed.
- *
- * `ascii` is the strict no-color, no-Unicode-extra tier; it is the
- * single safe option for plain log / file consumers.
- *
- * Why `PEAKS_STATUSLINE_ASCII` outranks `NO_COLOR`:
- *   The two env vars are NOT redundant. `NO_COLOR` (https://no-color.org)
- *   is the cross-industry signal that NO escape sequences should be emitted
- *   — its only effect is "ANSI off". The Unicode-extra glyphs (●, █, ░, etc.)
- *   are NOT ANSI escape sequences; they are UTF-8 characters and `NO_COLOR`
- *   does not address them. `PEAKS_STATUSLINE_ASCII` is the adapter-internal
- *   "signal source is a tiny terminal without UTF-8" override and drops the
- *   glyphs to ASCII shape as well. Both are correct signals about
- *   different concerns; the ASCII override wins because it is strictly
- *   narrower (a tiny terminal needs both no-ANSI AND no-Unicode-extra).
- *
- * The deliberate ordering keeps the rendered text ANSI-free when the consumer
- * is a logger, a file, or any non-interactive sink, and only enables ANSI
- * under an explicit supported condition (TTY + no env veto).
- */
 export declare function resolveStatusLineCapability(input: {
     readonly env: NodeJS.ProcessEnv;
     readonly isTTY: boolean;
     readonly forced?: StatusLineCapability;
 }): StatusLineCapability;
+export declare function isNoColorEnv(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Visible-character width of an ANSI-bearing string. Skips every
+ * `\x1b[...m` escape so the count reflects what the terminal paints,
+ * not the byte length on the wire.
+ */
+export declare function visibleCharWidth(s: string): number;
+interface AnsiToken {
+    readonly kind: 'text' | 'esc';
+    readonly value: string;
+}
+/**
+ * Split an ANSI string into a flat token stream. Escape sequences are
+ * grouped as `\x1b[...m` (single token, kind='esc'); everything else
+ * is grouped as a single 'text' run. Used by {@link applyMarquee} to
+ * locate visible-cell ranges inside an SGR-bearing string.
+ */
+export declare function tokenizeAnsi(s: string): readonly AnsiToken[];
+/**
+ * Apply the marquee highlight band to an ANSI-bearing string. Pure.
+ * - `bandStart` / `bandEnd` are visible-cell indices (0-based).
+ * - Cells in [bandStart, bandEnd] receive a `\x1b[1;38;2;224;224;224m`
+ *   prefix; cells after the band receive the closing `\x1b[0m` reset
+ *   so the rest of the line keeps its original SGR.
+ * - Empty strings and zero-width bands return the input unchanged.
+ */
+export declare function applyMarqueeHighlight(s: string, bandStart: number, bandEnd: number): string;
+/**
+ * Compute the marquee band for a string at time `nowMs` and re-emit
+ * the string with the band applied. ASCII tier is a pass-through (no
+ * SGR to inject) — the scanner has no visible effect on plain text.
+ */
+export declare function applyMarquee(s: string, nowMs: number, capability: StatusLineCapability): string;
 /**
  * Render the status line. Pure — no I/O, no side effects. The output is
  * a single short line suitable for the bottom-of-terminal status bar.
@@ -85,5 +63,17 @@ export declare function resolveStatusLineCapability(input: {
  * Compact-state precedence: when `model.compact.kind !== 'none'` the
  * compact bar replaces the active/idle/stale content. The C1 baseline
  * line is preserved when the compact state is `none`.
+ *
+ * The full line is wrapped by {@link applyMarquee} so the brand-purple
+ * text + non-focal bar cells share a single colour surface while the
+ * scanner band paints its `#E0E0E0` highlight over a moving slice.
+ *
+ * Idle suppression: the marquee is OFF when `model.state === 'idle'`
+ * (and no compact state is active). Idle keeps the slow-blink `○`
+ * as the only motion — the user is asking whether the harness is
+ * running a skill; the scan band would compete for attention and
+ * obscure that question. Active / stale / invalid-presence / compact
+ * states all keep the marquee.
  */
-export declare function renderStatusLine(model: StatusLineModel, options?: StatusLineRenderOptions): string;
+export declare function renderStatusLine(model: StatusLineModel, options?: StatusLineRenderOptions, env?: NodeJS.ProcessEnv): string;
+export {};