peaks-loop 3.0.0

package/dist/src/services/scan/type-sanity-service.js

@@ -0,0 +1,116 @@
+import { execFileSync } from 'node:child_process';
+import { extname, basename } from 'node:path';
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.cpp', '.c', '.h', '.cs', '.rb', '.php', '.scala', '.dart', '.less', '.scss', '.sass', '.css']);
+const DOCS_EXTENSIONS = new Set(['.md', '.mdx', '.rst', '.txt']);
+const LOCKFILE_NAMES = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb', 'Cargo.lock', 'Gemfile.lock', 'composer.lock', 'go.sum', 'poetry.lock']);
+const CONFIG_NAMES = new Set(['package.json', 'tsconfig.json', 'tsconfig.base.json', 'vite.config.ts', 'vite.config.js', 'webpack.config.js', 'next.config.js', 'next.config.ts', '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.prettierrc', '.prettierrc.json', 'eslint.config.js', '.gitignore', '.npmrc', 'docker-compose.yml', 'docker-compose.yaml', 'Dockerfile', 'Makefile', '.editorconfig', 'tailwind.config.js', 'tailwind.config.ts', 'postcss.config.js', 'commitlint.config.js', 'lefthook.yml', 'turbo.json', 'lerna.json', 'pnpm-workspace.yaml', 'nx.json']);
+const CONFIG_EXTENSIONS = new Set(['.toml', '.ini', '.cfg', '.env']);
+function classifyFile(filePath) {
+    const name = basename(filePath);
+    const ext = extname(filePath).toLowerCase();
+    if (LOCKFILE_NAMES.has(name))
+        return 'lockfile';
+    if (CONFIG_NAMES.has(name))
+        return 'config';
+    if (CONFIG_EXTENSIONS.has(ext))
+        return 'config';
+    if (filePath.startsWith('.github/') || filePath.includes('/workflows/') || name === 'release.yml' || name.endsWith('.yml') || name.endsWith('.yaml'))
+        return 'config';
+    if (DOCS_EXTENSIONS.has(ext))
+        return 'docs';
+    // Test files: anything under tests/, __tests__/, or matching *.test.*, *.spec.*
+    if (/\b(?:tests?|__tests__|__mocks__|spec)\b/.test(filePath) || /\.(test|spec)\.[a-z]+$/i.test(name))
+        return 'test';
+    if (SOURCE_EXTENSIONS.has(ext))
+        return 'source';
+    return 'unknown';
+}
+/**
+ * Peaks' own artifact workspace. Changes here (PRD/RD/QA markdown, session
+ * state) are never the "code change" a request type describes, so they must be
+ * excluded from the diff — otherwise a PRD-planning-phase handoff that only
+ * wrote `.peaks/**` markdown would be misclassified as a docs change.
+ */
+function isArtifactWorkspaceFile(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized === '.peaks' || normalized.startsWith('.peaks/');
+}
+function tryGitDiffFiles(projectRoot, baseRef) {
+    try {
+        // Combine: tracked changes vs baseRef + untracked files. Use porcelain status for untracked too.
+        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', baseRef], { encoding: 'utf8' });
+        const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
+        const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const merged = Array.from(new Set([...tracked, ...untracked])).filter((file) => !isArtifactWorkspaceFile(file));
+        return { ok: true, files: merged };
+    }
+    catch {
+        return { ok: false, files: [] };
+    }
+}
+function buildBreakdown(files) {
+    const grouped = new Map();
+    for (const file of files) {
+        const category = classifyFile(file);
+        const list = grouped.get(category) ?? [];
+        list.push(file);
+        grouped.set(category, list);
+    }
+    return Array.from(grouped.entries()).map(([category, examples]) => ({
+        category,
+        count: examples.length,
+        examples: examples.slice(0, 5)
+    }));
+}
+function suggestTypes(breakdown) {
+    const counts = { source: 0, config: 0, docs: 0, lockfile: 0, test: 0, unknown: 0 };
+    for (const entry of breakdown)
+        counts[entry.category] = entry.count;
+    const hasSource = counts.source > 0;
+    const hasConfig = counts.config > 0;
+    const hasDocs = counts.docs > 0;
+    const hasLockfile = counts.lockfile > 0;
+    const hasTest = counts.test > 0;
+    if (!hasSource && !hasConfig && hasDocs)
+        return ['docs'];
+    if (!hasSource && !hasDocs && hasConfig)
+        return ['config'];
+    if (!hasSource && !hasDocs && !hasConfig && hasLockfile)
+        return ['chore'];
+    if (!hasSource && !hasDocs && !hasConfig && !hasLockfile && hasTest)
+        return ['bugfix', 'refactor'];
+    if (hasSource)
+        return ['feature', 'bugfix', 'refactor'];
+    return ['feature', 'bugfix', 'refactor', 'config', 'docs', 'chore'];
+}
+function isConsistent(declared, suggested) {
+    return suggested.includes(declared);
+}
+function buildRationale(declared, breakdown, suggested, consistent) {
+    const summary = breakdown.map((entry) => `${entry.category}=${entry.count}`).join(', ');
+    if (consistent) {
+        return `declared --type=${declared} is consistent with the changed files (${summary})`;
+    }
+    return `declared --type=${declared} disagrees with the changed files (${summary}); suggested types: ${suggested.join(' | ')}`;
+}
+export function checkTypeSanity(options) {
+    const baseRef = options.baseRef ?? 'HEAD';
+    const { ok: gitAvailable, files } = tryGitDiffFiles(options.projectRoot, baseRef);
+    const breakdown = buildBreakdown(files);
+    const suggested = suggestTypes(breakdown);
+    const consistent = !gitAvailable ? true : files.length === 0 ? true : isConsistent(options.declaredType, suggested);
+    return {
+        declaredType: options.declaredType,
+        gitAvailable,
+        changedFiles: files,
+        breakdown,
+        suggestedTypes: suggested,
+        consistent,
+        rationale: !gitAvailable
+            ? 'git unavailable or not a git repository — type sanity check skipped (returns consistent=true)'
+            : files.length === 0
+                ? `no changes detected against ${baseRef} — type sanity check skipped (returns consistent=true)`
+                : buildRationale(options.declaredType, breakdown, suggested, consistent)
+    };
+}

package/dist/src/services/security/safe-settings-path.d.ts

@@ -0,0 +1,12 @@
+/** Build the canonical record path for a given session/rid/timestamp. */
+export declare function dispatchRecordPath(projectRoot: string, sid: string, rid: string, ts?: Date): string;
+/** The directory under which dispatch records live. */
+export declare function dispatchRecordsDir(projectRoot: string, sid: string): string;
+/**
+ * Assert that `recordPath` lives under `projectRoot/.peaks/_sub_agents/<sid>/`.
+ * Rejects symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_RECORD_PATH'` on rejection so
+ * the CLI can map to `{ok: false, code: "INVALID_RECORD_PATH"}`.
+ */
+export declare function assertSafeDispatchRecordPath(recordPath: string, projectRoot: string): string;

package/dist/src/services/security/safe-settings-path.js

@@ -0,0 +1,104 @@
+/**
+ * R-2 path-safety guard for sub-agent state files.
+ *
+ * Slice 2026-06-07-sub-agent-dispatch-decouple (G4) — reuses the same
+ * R-2 symlink/junction guard as `assertSafeSettingsFile` for
+ * `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json` paths.
+ *
+ * Why a separate helper:
+ *   - The settings-file guard is a per-IDE 8th field (settings.json path);
+ *     this one is for runtime sub-agent trace records.
+ *   - Both reject paths that resolve outside the project root after
+ *     symlink resolution, and both reject `..` segments before
+ *     resolution (defense in depth).
+ *
+ * The guard is intentionally small and pure (no IO beyond `realpathSync`)
+ * so it can be called from CLI handlers and from service helpers alike.
+ */
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+const SUB_AGENTS_DIR = '_sub_agents';
+/** Build the canonical record path for a given session/rid/timestamp. */
+export function dispatchRecordPath(projectRoot, sid, rid, ts = new Date()) {
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    const safeRid = sanitizeSegment(rid, 'requestId');
+    const tsCompact = ts.toISOString().replace(/[:.]/g, '-');
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid, `dispatch-${safeRid}-${tsCompact}.json`);
+}
+/** The directory under which dispatch records live. */
+export function dispatchRecordsDir(projectRoot, sid) {
+    const safeSid = sanitizeSegment(sid, 'sessionId');
+    return resolve(projectRoot, '.peaks', SUB_AGENTS_DIR, safeSid);
+}
+/**
+ * Assert that `recordPath` lives under `projectRoot/.peaks/_sub_agents/<sid>/`.
+ * Rejects symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_RECORD_PATH'` on rejection so
+ * the CLI can map to `{ok: false, code: "INVALID_RECORD_PATH"}`.
+ */
+export function assertSafeDispatchRecordPath(recordPath, projectRoot) {
+    if (!isAbsolute(recordPath)) {
+        throw invalidPathError(recordPath, 'must be absolute');
+    }
+    // Reject lexical `..` segments in the raw path BEFORE the OS-level resolver
+    // collapses them. POSIX `path.normalize` will turn `/a/b/../c` into `/a/c`,
+    // silently dropping the `..` — and that is exactly the symlink/junction
+    // escape we are guarding against. Test the raw string form.
+    const rawSegments = recordPath.split(/[\\/]/);
+    if (rawSegments.includes('..')) {
+        throw invalidPathError(recordPath, 'must not contain .. segments');
+    }
+    const expected = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+    const rel = relative(expected, recordPath);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw invalidPathError(recordPath, 'must be under .peaks/_sub_agents/');
+    }
+    let realRecord;
+    let realRoot;
+    try {
+        // For existing files, realpathSync resolves symlinks/junctions.
+        // For new files (the common case for `dispatch` CLI writing the
+        // record for the first time), we realpath the parent + check the
+        // leaf's basename shape.
+        const parent = dirname(recordPath);
+        const realParent = realpathSync(parent);
+        realRecord = resolve(realParent, recordPath.slice(parent.length + 1));
+        realRoot = realpathSync(projectRoot);
+    }
+    catch (error) {
+        // Realpath can fail if the parent does not exist yet (CLI is about
+        // to create it). Fall back to lexical comparison against the
+        // canonical projectRoot — the write will then create the file,
+        // and any symlink in the parent will be caught on the next read.
+        const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
+        const rel2 = relative(fallback, recordPath);
+        if (rel2.startsWith('..') || isAbsolute(rel2)) {
+            throw invalidPathError(recordPath, 'must be under .peaks/_sub_agents/');
+        }
+        return recordPath;
+    }
+    const realRel = relative(realRoot, realRecord);
+    if (realRel.startsWith('..' + sep) || realRel === '..' || isAbsolute(realRel)) {
+        throw invalidPathError(recordPath, 'escapes project root via symlink');
+    }
+    return realRecord;
+}
+function sanitizeSegment(segment, label) {
+    if (typeof segment !== 'string' || segment.length === 0) {
+        throw new Error(`Invalid ${label}: empty`);
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(segment)) {
+        throw new Error(`Invalid ${label}: must match [A-Za-z0-9._-]+ (got ${JSON.stringify(segment)})`);
+    }
+    if (segment.includes('..')) {
+        throw new Error(`Invalid ${label}: must not contain ..`);
+    }
+    return segment;
+}
+function invalidPathError(path, reason) {
+    const err = new Error(`Unsafe dispatch record path (${reason}): ${path}`);
+    err.code = 'INVALID_RECORD_PATH';
+    err.path = path;
+    return err;
+}

package/dist/src/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/src/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/src/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-solo → 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;