peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,20 @@
+import type { IndexFile } from "./types.js";
+export declare class POOL_READ_ERROR extends Error {
+}
+/** 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 declare function readPool({ home }: {
+    home: string;
+}): IndexFile;

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-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;