peaks-loop 4.0.0-beta.6 → 4.0.0-beta.8

package/dist/src/services/session/binding-store.js

@@ -1,509 +0,0 @@
-/**
- * Binding store — v2.16.0 multi-Claude-instance sentinel layer.
- *
- * Pre-v2.16.0 binding schema was a single-session record:
- *   { sessionId, createdAt, projectRoot }
- *
- * v2.16.0 schema is a multi-instance registry with conflict-detection
- * sentinel fields (ownerHint, pid, lastHeartbeat, instances Map).
- * See PRD `001-2026-06-29-v2-16-0-change-id-axis-removal` AC-8.
- *
- * The store keeps a one-shot migration from the legacy schema:
- * legacy single-session binding → v2.16.0 instances Map with one entry,
- * ownerHint sourced from env (PEAKS_OUTER_SESSION_ID fallback
- * CLAUDE_CODE_SESSION_ID fallback 'unknown').
- *
- * Each write produces an atomic writeFileSync — partial writes from
- * crashed processes are acceptable because re-read will re-validate
- * with the zod schema and either re-migrate or rebuild empty.
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { copyFileSync, openSync, closeSync, constants as fsConstants } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { z } from 'zod';
-export const InstanceRecordSchema = z.object({
-    startedAt: z.string().datetime(),
-    roles: z.array(z.string()).default([]),
-    callerId: z.string().min(1),
-    lastHeartbeat: z.string().datetime()
-});
-export const BindingSchema = z.object({
-    ownerHint: z.string().min(1),
-    pid: z.number().int().positive(),
-    lastHeartbeat: z.string().datetime(),
-    scope: z.string().min(1),
-    instances: z.record(z.string(), InstanceRecordSchema)
-});
-const LEGACY_SESSION_FILE = '.session.json';
-const CANONICAL_SESSION_FILE = join('_runtime', 'session.json');
-function getCanonicalPath(projectRoot) {
-    return join(projectRoot, '.peaks', CANONICAL_SESSION_FILE);
-}
-function getLegacyPath(projectRoot) {
-    return join(projectRoot, '.peaks', LEGACY_SESSION_FILE);
-}
-function getCurrentOuterSessionId() {
-    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
-    if (typeof peaks === 'string' && peaks.length > 0)
-        return peaks;
-    const claude = process.env.CLAUDE_CODE_SESSION_ID;
-    if (typeof claude === 'string' && claude.length > 0)
-        return claude;
-    return 'unknown';
-}
-/**
- * Build the *real* caller identity for the current process.
- *
- * v2.18.0 P0 fix: `getCurrentOuterSessionId()` alone is not a
- * process-unique signal — two Claude Code windows on the same
- * host share the same `CLAUDE_CODE_SESSION_ID` (it is bound to
- * the IDE / app session, not the window), and a CI runner with
- * both env vars unset returns the literal `'unknown'` sentinel
- * for every process. Suffixing with `process.pid` makes the
- * callerId process-unique without changing the surface (no new
- * env var, no new schema field), preserving the AC-5 hard rule
- * that "one Claude instance keeps one sid across multiple
- * peaks-* skill activations" — a single process keeps a constant
- * pid across the whole run, including `/compact`.
- *
- * The `#` separator is safe here: `InstanceRecord.callerId` uses
- * `z.string().min(1)` (no regex), and the v2.16.0 binding schema
- * has no path-embedding constraint on callerId (unlike the
- * platform D1 `CALLER_ID_REGEX` which only applies to the CLI
- * surface in `caller-id-types.ts`).
- *
- * The resulting string is stored on `InstanceRecord.callerId`
- * AND on `Binding.ownerHint` (advisory metadata; kept for
- * back-compat reads of the v2.16.0 schema).
- */
-function getCurrentCallerId() {
-    const envSignal = getCurrentOuterSessionId();
-    return `${envSignal}#${process.pid}`;
-}
-function nowIso() {
-    return new Date().toISOString();
-}
-function backupCorruptFile(projectRoot) {
-    const canonical = getCanonicalPath(projectRoot);
-    if (!existsSync(canonical))
-        return;
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const backup = `${canonical}.bak.${stamp}`;
-    try {
-        copyFileSync(canonical, backup);
-    }
-    catch (err) {
-        // best-effort backup; do not block rebuild. Surface a warning so
-        // silent-warning-detector does not flag this branch.
-        process.stderr.write(`[binding-store] backup ${canonical} → ${backup} failed: ${String(err)}\n`);
-    }
-}
-/**
- * Read the project-level binding.
- *
- * Returns null if no binding exists. Returns a migrated v2.16.0 binding
- * when legacy schema is detected (one-shot auto-migration; original
- * legacy file is NOT deleted — caller decides retention policy).
- *
- * On schema violation (corrupt JSON or missing required field), the file
- * is backed up as `<path>.bak.<ISO>` and null is returned. The next
- * write call will recreate the binding from scratch.
- */
-export function readBinding(projectRoot) {
-    const canonical = getCanonicalPath(projectRoot);
-    const legacy = getLegacyPath(projectRoot);
-    const pathToRead = existsSync(canonical) ? canonical : existsSync(legacy) ? legacy : null;
-    if (pathToRead === null)
-        return null;
-    let raw;
-    try {
-        raw = readFileSync(pathToRead, 'utf8');
-    }
-    catch (err) {
-        // IO failure is indistinguishable from "no binding" to the caller;
-        // log the cause for forensics and return null so ensureSession can
-        // rebuild from scratch.
-        process.stderr.write(`[binding-store] read ${pathToRead} failed: ${String(err)}\n`);
-        return null;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        backupCorruptFile(projectRoot);
-        return null;
-    }
-    // v2.16.0 schema hit.
-    const validated = BindingSchema.safeParse(parsed);
-    if (validated.success) {
-        return validated.data;
-    }
-    // Legacy schema (single-session): auto-migrate to one-instance registry.
-    const legacyShape = parsed;
-    if (typeof legacyShape.sessionId === 'string' &&
-        typeof legacyShape.createdAt === 'string' &&
-        typeof legacyShape.projectRoot === 'string') {
-        // Auto-migrate marks lastHeartbeat as `now` (not `createdAt`) so the
-        // migrated instance does NOT immediately appear stale to AC-10.
-        // Legacy bindings date from the pre-v2.16.0 single-session era;
-        // their createdAt predates the binding sentinel concept entirely.
-        const migratedAt = nowIso();
-        const binding = {
-            ownerHint: getCurrentCallerId(),
-            pid: process.pid,
-            lastHeartbeat: migratedAt,
-            scope: legacyShape.projectRoot,
-            instances: {
-                [legacyShape.sessionId]: {
-                    startedAt: legacyShape.createdAt,
-                    roles: [],
-                    callerId: getCurrentCallerId(),
-                    lastHeartbeat: migratedAt
-                }
-            }
-        };
-        return binding;
-    }
-    // Unrecognised shape: back up and return null.
-    backupCorruptFile(projectRoot);
-    return null;
-}
-/**
- * Persist the binding atomically. Caller passes the full binding object;
- * the store does NOT merge — pass the result of `readBinding` (or
- * `withInstance`) and modify in place.
- */
-export function writeBinding(projectRoot, binding) {
-    const canonical = getCanonicalPath(projectRoot);
-    const dir = dirname(canonical);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    const validated = BindingSchema.parse(binding);
-    writeFileSync(canonical, JSON.stringify(validated, null, 2), 'utf8');
-}
-/**
- * Register a Claude instance by `callerId`. Idempotent: if an instance
- * with the given callerId already exists, refresh its `lastHeartbeat`
- * and return its sid. Otherwise pick the next free sid slot (creating
- * a new session id under `instances`) and return it.
- *
- * This is the D2 Claude-instance-level binding primitive — a single
- * Claude instance keeps one sid across multiple peaks-* skill
- * activations; binding.instances[<sid>].roles accumulates the skill
- * names (peaks-code → peaks-rd → peaks-qa in the same Claude run).
- *
- * The caller is responsible for actually creating the session dir via
- * `initWorkspace` and storing per-session meta via `setSessionMeta`.
- */
-export function registerInstance(projectRoot, opts) {
-    const existing = readBinding(projectRoot);
-    // v2.18.0 P0 fix: an empty callerId now defaults to the
-    // process-unique `getCurrentCallerId()` (env signal + pid),
-    // NOT the bare `'unknown'` sentinel. This prevents two
-    // no-callerId callers from sharing a sid via the sentinel
-    // collision that v2.17.0 had.
-    const callerId = opts.callerId.length > 0 ? opts.callerId : getCurrentCallerId();
-    const roles = opts.roles ?? [];
-    const now = nowIso();
-    if (existing) {
-        // Resume path: caller is an already-known instance.
-        if (opts.existingSid) {
-            const inst = existing.instances[opts.existingSid];
-            if (inst) {
-                const mergedRoles = Array.from(new Set([...inst.roles, ...roles]));
-                const next = {
-                    ...existing,
-                    lastHeartbeat: now,
-                    instances: {
-                        ...existing.instances,
-                        [opts.existingSid]: { ...inst, roles: mergedRoles, lastHeartbeat: now }
-                    }
-                };
-                writeBinding(projectRoot, next);
-                return { binding: next, sid: opts.existingSid };
-            }
-        }
-        // Auto-resume: caller already has an instance in this scope —
-        // append roles and refresh heartbeat instead of creating a new
-        // sid. This is the AC-5 Claude-instance-level hard rule: a
-        // single Claude caller keeps one sid across multiple peaks-*
-        // skill activations.
-        const existingSidForCaller = Object.entries(existing.instances).find(([, inst]) => inst.callerId === callerId)?.[0];
-        if (existingSidForCaller) {
-            const inst = existing.instances[existingSidForCaller];
-            const mergedRoles = Array.from(new Set([...inst.roles, ...roles]));
-            const next = {
-                ...existing,
-                lastHeartbeat: now,
-                instances: {
-                    ...existing.instances,
-                    [existingSidForCaller]: { ...inst, roles: mergedRoles, lastHeartbeat: now }
-                }
-            };
-            writeBinding(projectRoot, next);
-            return { binding: next, sid: existingSidForCaller };
-        }
-        // New caller joining an existing scope.
-        const sid = generateSid();
-        const next = {
-            ...existing,
-            lastHeartbeat: now,
-            instances: {
-                ...existing.instances,
-                [sid]: {
-                    startedAt: now,
-                    roles,
-                    callerId,
-                    lastHeartbeat: now
-                }
-            }
-        };
-        writeBinding(projectRoot, next);
-        return { binding: next, sid };
-    }
-    // First binding in this scope.
-    const sid = opts.existingSid ?? generateSid();
-    const binding = {
-        ownerHint: callerId,
-        pid: process.pid,
-        lastHeartbeat: now,
-        scope: projectRoot,
-        instances: {
-            [sid]: {
-                startedAt: now,
-                roles,
-                callerId,
-                lastHeartbeat: now
-            }
-        }
-    };
-    writeBinding(projectRoot, binding);
-    return { binding, sid };
-}
-/**
- * Touch the `lastHeartbeat` for a specific instance. Used by the
- * Doctor periodic loop (AC-10) and by the Skill presence `startup`
- * gate.
- */
-export function heartbeat(projectRoot, sid) {
-    const existing = readBinding(projectRoot);
-    if (!existing)
-        return null;
-    const inst = existing.instances[sid];
-    if (!inst)
-        return null;
-    const now = nowIso();
-    const next = {
-        ...existing,
-        lastHeartbeat: now,
-        instances: {
-            ...existing.instances,
-            [sid]: { ...inst, lastHeartbeat: now }
-        }
-    };
-    writeBinding(projectRoot, next);
-    return next;
-}
-/**
- * Drop an instance entry from the binding. Used when the last peaks-*
- * skill on a Claude instance exits (AC-7: all skills inactive →
- * no record). Returns the updated binding (or null if no instances
- * remain and the caller wants to delete the binding entirely).
- */
-export function dropInstance(projectRoot, sid) {
-    const existing = readBinding(projectRoot);
-    if (!existing)
-        return null;
-    if (!existing.instances[sid])
-        return existing;
-    const { [sid]: _removed, ...rest } = existing.instances;
-    void _removed;
-    if (Object.keys(rest).length === 0)
-        return null;
-    const next = { ...existing, instances: rest, lastHeartbeat: nowIso() };
-    writeBinding(projectRoot, next);
-    return next;
-}
-/**
- * Drop stale instances (lastHeartbeat older than `ttlMs`). Returns
- * the list of dropped sid values so the caller can log them. Used
- * by AC-10 Doctor.
- */
-export function dropStale(projectRoot, ttlMs) {
-    const existing = readBinding(projectRoot);
-    if (!existing)
-        return { binding: null, dropped: [] };
-    const cutoff = Date.now() - ttlMs;
-    const dropped = [];
-    const kept = {};
-    for (const [sid, inst] of Object.entries(existing.instances)) {
-        const t = Date.parse(inst.lastHeartbeat);
-        if (Number.isFinite(t) && t < cutoff) {
-            dropped.push(sid);
-        }
-        else {
-            kept[sid] = inst;
-        }
-    }
-    if (dropped.length === 0)
-        return { binding: existing, dropped };
-    if (Object.keys(kept).length === 0)
-        return { binding: null, dropped };
-    const next = { ...existing, instances: kept, lastHeartbeat: nowIso() };
-    writeBinding(projectRoot, next);
-    return { binding: next, dropped };
-}
-/**
- * Look up the active sid for a Claude caller. Returns null if this
- * caller has never registered or its instance was dropped.
- *
- * The caller is typically the outer-session-id (PEAKS_OUTER_SESSION_ID
- * with CLAUDE_CODE_SESSION_ID fallback) — same string used as
- * `ownerHint` and `callerId`.
- */
-export function findSidByCaller(projectRoot, callerId) {
-    const existing = readBinding(projectRoot);
-    if (!existing)
-        return null;
-    for (const [sid, inst] of Object.entries(existing.instances)) {
-        if (inst.callerId === callerId)
-            return sid;
-    }
-    return null;
-}
-function generateSid() {
-    const now = new Date();
-    const yyyy = now.getUTCFullYear();
-    const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
-    const dd = String(now.getUTCDate()).padStart(2, '0');
-    const rand = Math.random().toString(36).slice(2, 8);
-    return `${yyyy}-${mm}-${dd}-session-${rand}`;
-}
-function acquireRebuildLock(projectRoot) {
-    const lockPath = join(projectRoot, '.peaks', '_runtime', '.rebuild-binding.lock');
-    const dir = dirname(lockPath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    try {
-        // O_EXCL (`wx` in Node): atomic create-or-fail. If the lock file
-        // already exists, another `rebuildBindingFromLegacy` invocation
-        // holds it. The holder is expected to release it via
-        // `closeSync` + `unlinkSync` (see `releaseRebuildLock`).
-        const fd = openSync(lockPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL);
-        return { fd, path: lockPath };
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === 'EEXIST')
-            return null;
-        throw err;
-    }
-}
-function releaseRebuildLock(lock) {
-    if (lock === null)
-        return;
-    try {
-        closeSync(lock.fd);
-    }
-    catch (err) {
-        // best-effort close; surface to stderr so silent-warning-detector
-        // does not flag the empty-catch. The next acquireRebuildLock will
-        // still detect the stale lock via EEXIST and treat it as held,
-        // which is the safer default.
-        process.stderr.write(`[binding-store] close rebuild lock ${lock.path} failed: ${String(err)}\n`);
-    }
-    try {
-        // unlinkSync is best-effort; a stale lock will be detected by
-        // existsSync on the next acquire and treated as a held lock
-        // (returning null), which is the safer default.
-        unlinkSync(lock.path);
-    }
-    catch (err) {
-        process.stderr.write(`[binding-store] unlink rebuild lock ${lock.path} failed: ${String(err)}\n`);
-    }
-}
-export function rebuildBindingFromLegacy(projectRoot) {
-    const lock = acquireRebuildLock(projectRoot);
-    if (lock === null) {
-        return {
-            rewritten: 0,
-            preserved: 0,
-            errors: ['another peaks doctor --rebuild-binding is in progress (lock held)'],
-            noop: true
-        };
-    }
-    try {
-        const binding = readBinding(projectRoot);
-        if (binding === null) {
-            // No binding to rebuild — idempotent no-op.
-            return { rewritten: 0, preserved: 0, errors: [], noop: true };
-        }
-        const errors = [];
-        let rewritten = 0;
-        let preserved = 0;
-        const nextInstances = {};
-        for (const [sid, inst] of Object.entries(binding.instances)) {
-            if (inst.callerId.includes('#')) {
-                // Already in the v2.18.0+ shape — keep as-is.
-                nextInstances[sid] = inst;
-                preserved += 1;
-                continue;
-            }
-            if (inst.callerId === 'unknown') {
-                // No identity to preserve — keep the instance as-is and
-                // report. Re-encoding `unknown#${pid}` would be a
-                // misleading claim about process-uniqueness (any two no-env
-                // processes share the `unknown` signal). Counts as
-                // `preserved` because the entry is unchanged on disk.
-                nextInstances[sid] = inst;
-                preserved += 1;
-                errors.push(`sid ${sid}: callerId="unknown" has no pid suffix source — skipped`);
-                continue;
-            }
-            nextInstances[sid] = { ...inst, callerId: `${inst.callerId}#${binding.pid}` };
-            rewritten += 1;
-        }
-        if (rewritten === 0) {
-            return { rewritten: 0, preserved, errors, noop: true };
-        }
-        const next = {
-            ...binding,
-            // Refresh ownerHint to the canonical v2.18.0+ shape so the
-            // advisory metadata is consistent with the rewritten instances.
-            ownerHint: binding.ownerHint.includes('#')
-                ? binding.ownerHint
-                : `${binding.ownerHint}#${binding.pid}`,
-            lastHeartbeat: nowIso(),
-            instances: nextInstances
-        };
-        // Atomic write: temp + rename, so a crash mid-write cannot leave
-        // a partial binding on disk.
-        const canonical = getCanonicalPath(projectRoot);
-        const dir = dirname(canonical);
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        const tmpPath = `${canonical}.tmp.${process.pid}`;
-        const validated = BindingSchema.parse(next);
-        writeFileSync(tmpPath, JSON.stringify(validated, null, 2), 'utf8');
-        try {
-            renameSync(tmpPath, canonical);
-        }
-        catch (renameErr) {
-            // Clean up the tmp file and surface the rename error.
-            try {
-                unlinkSync(tmpPath);
-            }
-            catch (cleanupErr) {
-                process.stderr.write(`[binding-store] cleanup tmp ${tmpPath} after rename failure failed: ${String(cleanupErr)}\n`);
-            }
-            throw renameErr;
-        }
-        return { rewritten, preserved, errors, noop: false };
-    }
-    finally {
-        releaseRebuildLock(lock);
-    }
-}

package/dist/src/services/session/caller-binding-service.d.ts

@@ -1,70 +0,0 @@
-/**
- * Caller-Binding Service (slice 020 — caller-keyed session binding).
- *
- * Each caller has its own on-disk binding file at
- * `.peaks/_runtime/callers/<callerId>.json`. This service is the
- * single read/write surface for that file. Legacy single-file bindings
- * (`.peaks/_runtime/session.json` and `.peaks/.session.json`) remain
- * readable for one minor release (M1 / M4); the read path falls back
- * to them with a `legacy-fallback-used: true` flag.
- *
- * M2: legacy bindings resolve into a synthetic callerId of the form
- * `legacy-<8hex-of-sha256(outerSessionId)>`, with `claudeSessionId`
- * and `projectRoot` as fallback hash inputs. The synthetic id is
- * permanent and recognisable by the `legacy-` prefix.
- *
- * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
- * for the freeze-in contract.
- */
-import { type CallerBinding } from './caller-id-types.js';
-/**
- * On-disk location of the per-caller binding file. P4 invariant:
- * the `callers/<callerId>.json` lives at `.peaks/_runtime/callers/`,
- * the same root as the per-peak session dirs.
- */
-export declare function getCallerBindingFile(projectRoot: string, callerId: string): string;
-/**
- * On-disk location of the per-(peak, caller) active-skill file. D6:
- * one file per (peakSessionId, callerId) pair; two callers bound to
- * the same peak session never clobber each other.
- */
-export declare function getActiveSkillFileForCaller(projectRoot: string, peakSessionId: string, callerId: string): string;
-/**
- * Resolve a stable, deterministic callerId for a legacy single-file
- * binding (M2). The hash input priority is:
- *
- *   1. `outerSessionId` (slice 018 stamped this on the per-peak
- *      session.json for sessions created after the slice shipped).
- *   2. `claudeSessionId` (legacy field name on pre-018 presence
- *      files; honour the read side so v1.2.x data does not lose its
- *      binding).
- *   3. `projectRoot` (truly anonymous case: pre-018 sessions that
- *      never recorded an outer / claude id).
- *
- * The synthetic id is `legacy-<first 8 hex chars of sha256(input)>`.
- * 32 bits of entropy is enough for typical on-disk state
- * (R1: <100 legacy peak sessions per project; the test asserts
- * uniqueness across 1000 synthetic ids).
- */
-export declare function synthesiseLegacyCallerId(input: string): string;
-/**
- * Read a per-caller binding file. Returns `null` if the file does
- * not exist, is malformed, or is for a different project (M1 back-compat
- * read returns the legacy file but only after the per-caller file is
- * absent).
- */
-export declare function getCallerBinding(projectRoot: string, callerId: string): CallerBinding | null;
-/**
- * Write or update a per-caller binding file. The caller is responsible
- * for the binding object (callerId must match the file stem, peakSessionId
- * must be a valid session id, projectRoot is canonicalized). Idempotent:
- * re-writing the same callerId overwrites the file.
- */
-export declare function setCallerBinding(projectRoot: string, callerId: string, binding: CallerBinding): void;
-/**
- * Enumerate the per-caller binding files under
- * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the
- * raw filenames (so callers can list orphan / legacy files without
- * re-reading).
- */
-export declare function listCallerBindings(projectRoot: string): CallerBinding[];