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

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

@@ -1,73 +0,0 @@
-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/src/services/sediment/pool-rebuild-index.d.ts

@@ -1,15 +0,0 @@
-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/src/services/sediment/pool-rebuild-index.js

@@ -1,28 +0,0 @@
-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/src/services/sediment/pool-write.d.ts

@@ -1,14 +0,0 @@
-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/src/services/sediment/pool-write.js

@@ -1,25 +0,0 @@
-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/src/services/sediment/promotion-gate.d.ts

@@ -1,12 +0,0 @@
-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/src/services/sediment/promotion-gate.js

@@ -1,20 +0,0 @@
-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/src/services/sediment/types.d.ts

@@ -1,52 +0,0 @@
-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/src/services/sediment/types.js

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

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

@@ -1,56 +0,0 @@
-/**
- * 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/src/services/session/binding-status-service.js

@@ -1,106 +0,0 @@
-/**
- * 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/src/services/session/binding-store.d.ts

@@ -1,161 +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 { 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;