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

package/dist/services/sediment/pool-read.js

@@ -0,0 +1,73 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveUserBeesDir, resolveSegmentsDir } from "./pool-paths.js";
+import { lintManifest } from "./manifest-lint.js";
+export class POOL_READ_ERROR extends Error {
+}
+function readJsonIfExists(p) {
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, "utf-8"));
+}
+function readBeeDir(home, name) {
+    const dir = join(resolveUserBeesDir({ home }), name);
+    const manifestPath = join(dir, "manifest.json");
+    const m = readJsonIfExists(manifestPath);
+    if (!m)
+        return null;
+    const r = lintManifest(m);
+    if (!r.ok)
+        return null;
+    return {
+        name: m.name,
+        kind: "bee",
+        path: `bees/${name}`,
+        source: m.source,
+        promotion_status: m.promotion_status,
+        segments: m.segments.map((s) => s.name),
+    };
+}
+function readSegmentDir(home, name) {
+    const dir = join(resolveSegmentsDir({ home }), name);
+    if (!existsSync(dir))
+        return null;
+    return {
+        name, kind: "segment", path: `segments/${name}`, source: "user", promotion_status: "stable",
+    };
+}
+/** Pure read of the in-memory pool index (Critical #2 fix).
+ *
+ *  CONTRACT: this function is a READ-ONLY computation. It MUST NOT
+ *  write `index.json` (or any other file) as a side-effect. The
+ *  "self-heal" property of rewriting index.json when it goes stale
+ *  belongs to `rebuildIndexFromFs`, not here. List / search / recent /
+ *  add-* verbs that need to mutate the on-disk cache should call
+ *  `rebuildIndexFromFs` explicitly.
+ *
+ *  Edge case: if the pool root does not yet exist, this returns an
+ *  empty index WITHOUT creating the directory. Callers that need a
+ *  materialized root should use `rebuildIndexFromFs` or `mkdirSync`
+ *  themselves.
+ */
+export function readPool({ home }) {
+    const entries = [];
+    const beesDir = resolveUserBeesDir({ home });
+    if (existsSync(beesDir)) {
+        for (const ent of readdirSync(beesDir, { withFileTypes: true })) {
+            if (!ent.isDirectory())
+                continue;
+            entries.push(...[readBeeDir(home, ent.name)].filter((e) => e !== null));
+        }
+    }
+    const segsDir = resolveSegmentsDir({ home });
+    if (existsSync(segsDir)) {
+        for (const ent of readdirSync(segsDir, { withFileTypes: true })) {
+            if (!ent.isDirectory())
+                continue;
+            entries.push(...[readSegmentDir(home, ent.name)].filter((e) => e !== null));
+        }
+    }
+    const idx = { schemaVersion: "peaks.pool/1", generatedAt: new Date().toISOString(), entries };
+    // Note: NO writeFileSync here. See Critical #2 fix.
+    return idx;
+}

package/dist/services/sediment/pool-rebuild-index.d.ts

@@ -0,0 +1,15 @@
+import type { IndexFile } from "./types.js";
+/**
+ * Rebuilds index.json from on-disk manifests/segments and writes the result.
+ *
+ * After the Critical #2 fix, `readPool` is a pure read (no filesystem
+ * side-effects). `rebuildIndexFromFs` is the single writer of
+ * `index.json`: it materializes the pool root if needed, walks the
+ * filesystem to build the in-memory index via `readPool`, and persists
+ * the result. Callers that need the on-disk cache up-to-date should
+ * call this function (or one of the add-* / rebuild-index CLI verbs
+ * which call it internally).
+ */
+export declare function rebuildIndexFromFs({ home }: {
+    home: string;
+}): IndexFile;

package/dist/services/sediment/pool-rebuild-index.js

@@ -0,0 +1,28 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolvePoolRoot } from "./pool-paths.js";
+import { readPool } from "./pool-read.js";
+/**
+ * Rebuilds index.json from on-disk manifests/segments and writes the result.
+ *
+ * After the Critical #2 fix, `readPool` is a pure read (no filesystem
+ * side-effects). `rebuildIndexFromFs` is the single writer of
+ * `index.json`: it materializes the pool root if needed, walks the
+ * filesystem to build the in-memory index via `readPool`, and persists
+ * the result. Callers that need the on-disk cache up-to-date should
+ * call this function (or one of the add-* / rebuild-index CLI verbs
+ * which call it internally).
+ */
+export function rebuildIndexFromFs({ home }) {
+    const root = resolvePoolRoot({ home });
+    if (!existsSync(root))
+        mkdirSync(root, { recursive: true });
+    const idx = readPool({ home });
+    // Trailing newline: POSIX-friendly (`cat`, `git diff`, log tailers all
+    // expect a final \n). The Minor #14 review confirmed we keep the current
+    // behavior rather than drop it — both are JSON-valid but the trailing
+    // newline matches the convention used by every other peaks-*.json file
+    // in the project (manifest.json, segment.json, etc.).
+    writeFileSync(join(root, "index.json"), JSON.stringify(idx, null, 2) + "\n");
+    return idx;
+}

package/dist/services/sediment/pool-write.d.ts

@@ -0,0 +1,14 @@
+import type { BeeManifest } from "./types.js";
+/**
+ * Atomically writes a BeeManifest to <home>/.peaks/skills/bees/<name>/manifest.json.
+ *
+ * Defense in depth:
+ *  - re-validates the manifest via lintManifestStrict (zod) before any FS work
+ *  - refuses to write under any path segment equal to ".system" (soft-protection)
+ *
+ * Atomicity is achieved via write-to-tmp + renameSync so readers either see the
+ * old file or the fully-written new file, never a half-written one.
+ */
+export declare function writeBeeManifest({ home }: {
+    home: string;
+}, m: BeeManifest): void;

package/dist/services/sediment/pool-write.js

@@ -0,0 +1,25 @@
+import { writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { assertNotSystemPath, resolveUserBeeDir } from "./pool-paths.js";
+import { lintManifestStrict } from "./manifest-lint.js";
+/**
+ * Atomically writes a BeeManifest to <home>/.peaks/skills/bees/<name>/manifest.json.
+ *
+ * Defense in depth:
+ *  - re-validates the manifest via lintManifestStrict (zod) before any FS work
+ *  - refuses to write under any path segment equal to ".system" (soft-protection)
+ *
+ * Atomicity is achieved via write-to-tmp + renameSync so readers either see the
+ * old file or the fully-written new file, never a half-written one.
+ */
+export function writeBeeManifest({ home }, m) {
+    const validated = lintManifestStrict(m);
+    const dir = resolveUserBeeDir({ home }, validated.name);
+    assertNotSystemPath(dir);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "manifest.json");
+    assertNotSystemPath(file);
+    const tmp = file + ".tmp";
+    writeFileSync(tmp, JSON.stringify(validated, null, 2) + "\n");
+    renameSync(tmp, file);
+}

package/dist/services/sediment/promotion-gate.d.ts

@@ -0,0 +1,12 @@
+import type { BeeManifest } from "./types.js";
+export interface GateInputs {
+    humanApproved: boolean;
+    smokeTestPresent: boolean;
+}
+export interface GateResult {
+    ok: boolean;
+    failedSubconditions: string[];
+}
+export declare function evaluateGate({ home }: {
+    home: string;
+}, m: BeeManifest, inputs: GateInputs): GateResult;

package/dist/services/sediment/promotion-gate.js

@@ -0,0 +1,20 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveUserBeeDir } from "./pool-paths.js";
+export function evaluateGate({ home }, m, inputs) {
+    if (m.source === "system") {
+        return { ok: true, failedSubconditions: [] };
+    }
+    const failed = [];
+    const rsPath = join(resolveUserBeeDir({ home }, m.name), "run-state.json");
+    const cycles = existsSync(rsPath)
+        ? JSON.parse(readFileSync(rsPath, "utf-8")).cycles
+        : 0;
+    if (cycles < m.promotion.minCycles)
+        failed.push("minCycles");
+    if (inputs.smokeTestPresent !== m.promotion.requiresSmokeTest)
+        failed.push("smokeTest");
+    if (m.promotion.requiresHumanApproval && !inputs.humanApproved)
+        failed.push("humanApproval");
+    return { ok: failed.length === 0, failedSubconditions: failed };
+}

package/dist/services/sediment/types.d.ts

@@ -0,0 +1,52 @@
+export type Source = "system" | "user";
+export type PromotionStatus = "candidate" | "stable" | "retired" | "system-stable";
+export interface Param {
+    name: string;
+    type: "string" | "number" | "boolean" | "json";
+    required: boolean;
+}
+export interface SegmentRef {
+    name: string;
+    inputs: Param[];
+    outputs: Param[];
+    sideEffects: string[];
+}
+export interface SkillEnvelopeRef {
+    path: string;
+    kind: "file" | "dir" | "script";
+}
+export interface SkillEnvelope {
+    preamble: string;
+    refs: SkillEnvelopeRef[];
+}
+export interface PromotionGate {
+    minCycles: number;
+    requiresHumanApproval: boolean;
+    requiresSmokeTest: boolean;
+    retireOnMissesInRow?: number;
+}
+export interface BeeManifest {
+    schemaVersion: "peaks.bee/1";
+    name: string;
+    source: Source;
+    promotion_status: PromotionStatus;
+    description: string;
+    segments: SegmentRef[];
+    entrypoint: SkillEnvelope;
+    promotion: PromotionGate;
+    createdBy: "human" | "llm";
+    lastTouchedAt: string;
+}
+export interface IndexEntry {
+    name: string;
+    kind: "bee" | "segment";
+    path: string;
+    source: Source;
+    promotion_status: PromotionStatus;
+    segments?: string[];
+}
+export interface IndexFile {
+    schemaVersion: "peaks.pool/1";
+    generatedAt: string;
+    entries: IndexEntry[];
+}

package/dist/services/sediment/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/session/binding-status-service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Binding status service — v2.18.2 read-only introspection helper.
+ *
+ * Surfaces the on-disk binding-store contents to the
+ * `peaks binding status` CLI command (follow-up issue #2, deferred
+ * from the v2.18.0 PRD §3.4 nice-to-have list).
+ *
+ * The service is intentionally read-only: it never calls
+ * `registerInstance`, `heartbeat`, `dropInstance`, or any other
+ * mutator. The only writes it performs are to stdout/stderr (the
+ * rendering layer). This is the v2.18.2 "no side effects on status"
+ * contract — a user running `peaks binding status` must not see their
+ * own binding change underneath them.
+ *
+ * Format modes:
+ * - `table` (default for non-TTY): ASCII table with columns
+ *   `sid | callerId | pid | roles | lastHeartbeat`. Designed to be
+ *   greppable and pipeable; no ANSI colour, no padding tricks.
+ * - `json` (default when `--json` is set): raw binding dump matching
+ *   the zod `BindingSchema` shape.
+ */
+import { type Binding, type InstanceRecord } from './binding-store.js';
+export type BindingStatusFormat = 'table' | 'json';
+export type BindingStatusView = {
+    /** The raw binding that was read (or `null` when no binding exists). */
+    binding: Binding | null;
+    /** The on-disk source of the binding (informational; the CLI uses this for the header). */
+    source: 'canonical' | 'legacy' | 'none';
+    /** The project root the binding was read from. */
+    projectRoot: string;
+    /** True when the binding's callerIds do not match the current outer-session-id env signal. */
+    stale: boolean;
+    /** The current outer-session-id resolved from PEAKS_OUTER_SESSION_ID / CLAUDE_CODE_SESSION_ID / 'unknown'. */
+    outerSessionId: string;
+};
+/**
+ * Read the binding from disk and assemble the read-only view. Pure
+ * helper that does no filesystem writes; safe to call from any test.
+ */
+export declare function loadBindingStatus(projectRoot: string): BindingStatusView;
+/**
+ * Render the binding as a pipeable ASCII table. The columns are fixed
+ * (no truncation, no wrapping) so a downstream `awk` / `cut` pipeline
+ * can be built against it. Returns the empty string (NOT a header
+ * row) when the binding has no instances, so callers can detect "no
+ * data" via the row count.
+ */
+export declare function formatTable(view: BindingStatusView): string;
+/**
+ * Render the binding as a JSON envelope. The shape mirrors
+ * `BindingSchema` (camelCase keys kept for back-compat with the
+ * existing v2.18.0 callers; instance fields are nested under
+ * `instances[<sid>]`).
+ */
+export declare function formatJson(view: BindingStatusView): Record<string, unknown>;
+export declare function isInstanceRecord(value: unknown): value is InstanceRecord;

package/dist/services/session/binding-status-service.js

@@ -0,0 +1,106 @@
+/**
+ * Binding status service — v2.18.2 read-only introspection helper.
+ *
+ * Surfaces the on-disk binding-store contents to the
+ * `peaks binding status` CLI command (follow-up issue #2, deferred
+ * from the v2.18.0 PRD §3.4 nice-to-have list).
+ *
+ * The service is intentionally read-only: it never calls
+ * `registerInstance`, `heartbeat`, `dropInstance`, or any other
+ * mutator. The only writes it performs are to stdout/stderr (the
+ * rendering layer). This is the v2.18.2 "no side effects on status"
+ * contract — a user running `peaks binding status` must not see their
+ * own binding change underneath them.
+ *
+ * Format modes:
+ * - `table` (default for non-TTY): ASCII table with columns
+ *   `sid | callerId | pid | roles | lastHeartbeat`. Designed to be
+ *   greppable and pipeable; no ANSI colour, no padding tricks.
+ * - `json` (default when `--json` is set): raw binding dump matching
+ *   the zod `BindingSchema` shape.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readBinding } from './binding-store.js';
+/**
+ * Read the binding from disk and assemble the read-only view. Pure
+ * helper that does no filesystem writes; safe to call from any test.
+ */
+export function loadBindingStatus(projectRoot) {
+    const binding = readBinding(projectRoot);
+    const canonicalExists = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'));
+    const legacyExists = existsSync(join(projectRoot, '.peaks', '.session.json'));
+    const source = canonicalExists ? 'canonical' : legacyExists ? 'legacy' : 'none';
+    const outerSessionId = readOuterSessionId();
+    const stale = binding === null
+        ? false
+        : !Object.values(binding.instances).some((inst) => inst.callerId.startsWith(outerSessionId));
+    return { binding, source, projectRoot, stale, outerSessionId };
+}
+function readOuterSessionId() {
+    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';
+}
+/**
+ * Render the binding as a pipeable ASCII table. The columns are fixed
+ * (no truncation, no wrapping) so a downstream `awk` / `cut` pipeline
+ * can be built against it. Returns the empty string (NOT a header
+ * row) when the binding has no instances, so callers can detect "no
+ * data" via the row count.
+ */
+export function formatTable(view) {
+    if (view.binding === null)
+        return '';
+    const rows = [];
+    for (const [sid, inst] of Object.entries(view.binding.instances)) {
+        rows.push([sid, inst.callerId, String(view.binding.pid), inst.roles.join(','), inst.lastHeartbeat]);
+    }
+    if (rows.length === 0)
+        return '';
+    const header = ['sid', 'callerId', 'pid', 'roles', 'lastHeartbeat'];
+    const all = [header, ...rows];
+    const widths = header.map((_, i) => Math.max(...all.map((r) => r[i].length)));
+    const pad = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ');
+    const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+    return [pad(header), sep, ...rows.map(pad)].join('\n');
+}
+/**
+ * Render the binding as a JSON envelope. The shape mirrors
+ * `BindingSchema` (camelCase keys kept for back-compat with the
+ * existing v2.18.0 callers; instance fields are nested under
+ * `instances[<sid>]`).
+ */
+export function formatJson(view) {
+    if (view.binding === null) {
+        return {
+            binding: null,
+            source: view.source,
+            projectRoot: view.projectRoot,
+            stale: view.stale,
+            outerSessionId: view.outerSessionId
+        };
+    }
+    return {
+        binding: view.binding,
+        source: view.source,
+        projectRoot: view.projectRoot,
+        stale: view.stale,
+        outerSessionId: view.outerSessionId
+    };
+}
+export function isInstanceRecord(value) {
+    // Cheap duck-type guard for tests that build a binding literal;
+    // canonical validation lives in `BindingSchema` from binding-store.
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return typeof v.startedAt === 'string' &&
+        Array.isArray(v.roles) &&
+        typeof v.callerId === 'string' &&
+        typeof v.lastHeartbeat === 'string';
+}

package/dist/services/session/binding-store.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 { z } from 'zod';
+export declare const InstanceRecordSchema: z.ZodObject<{
+    startedAt: z.ZodString;
+    roles: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    callerId: z.ZodString;
+    lastHeartbeat: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    startedAt: string;
+    roles: string[];
+    callerId: string;
+    lastHeartbeat: string;
+}, {
+    startedAt: string;
+    callerId: string;
+    lastHeartbeat: string;
+    roles?: string[] | undefined;
+}>;
+export declare const BindingSchema: z.ZodObject<{
+    ownerHint: z.ZodString;
+    pid: z.ZodNumber;
+    lastHeartbeat: z.ZodString;
+    scope: z.ZodString;
+    instances: z.ZodRecord<z.ZodString, z.ZodObject<{
+        startedAt: z.ZodString;
+        roles: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        callerId: z.ZodString;
+        lastHeartbeat: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        startedAt: string;
+        roles: string[];
+        callerId: string;
+        lastHeartbeat: string;
+    }, {
+        startedAt: string;
+        callerId: string;
+        lastHeartbeat: string;
+        roles?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    lastHeartbeat: string;
+    ownerHint: string;
+    pid: number;
+    scope: string;
+    instances: Record<string, {
+        startedAt: string;
+        roles: string[];
+        callerId: string;
+        lastHeartbeat: string;
+    }>;
+}, {
+    lastHeartbeat: string;
+    ownerHint: string;
+    pid: number;
+    scope: string;
+    instances: Record<string, {
+        startedAt: string;
+        callerId: string;
+        lastHeartbeat: string;
+        roles?: string[] | undefined;
+    }>;
+}>;
+export type InstanceRecord = z.infer<typeof InstanceRecordSchema>;
+export type Binding = z.infer<typeof BindingSchema>;
+/**
+ * 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 declare function readBinding(projectRoot: string): Binding | 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 declare function writeBinding(projectRoot: string, binding: Binding): void;
+/**
+ * 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 declare function registerInstance(projectRoot: string, opts: {
+    callerId: string;
+    roles?: string[];
+    existingSid?: string;
+}): {
+    binding: Binding;
+    sid: string;
+};
+/**
+ * Touch the `lastHeartbeat` for a specific instance. Used by the
+ * Doctor periodic loop (AC-10) and by the Skill presence `startup`
+ * gate.
+ */
+export declare function heartbeat(projectRoot: string, sid: string): Binding | null;
+/**
+ * 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 declare function dropInstance(projectRoot: string, sid: string): Binding | null;
+/**
+ * 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 declare function dropStale(projectRoot: string, ttlMs: number): {
+    binding: Binding | null;
+    dropped: string[];
+};
+/**
+ * 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 declare function findSidByCaller(projectRoot: string, callerId: string): string | null;
+export type RebuildResult = {
+    rewritten: number;
+    preserved: number;
+    errors: string[];
+    /** True when no legacy entries were present and the file is unchanged. */
+    noop: boolean;
+};
+export declare function rebuildBindingFromLegacy(projectRoot: string): RebuildResult;