lazyopencode-core 0.0.1

package/dist/hooks/runtime.js

@@ -0,0 +1,653 @@
+import { existsSync } from "node:fs";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { BackgroundJobBoard } from "./background-job-board.js";
+import { defaultCouncilConfig } from "../council/index.js";
+import { getSkillsDir } from "../skills/index.js";
+export function createLazyRuntime(ctx = {}) {
+    const scope = createScope(ctx);
+    const config = resolveLazyConfig(undefined, scope);
+    const jobBoard = new BackgroundJobBoard({
+        maxReusablePerAgent: config.maxSessionsPerAgent,
+    });
+    const sessionAgentMap = new Map();
+    const sessionDepth = new Map();
+    const workflow = createEmptyTrace();
+    let contextStats = createEmptyContextStats(config.maxMessages);
+    let closeReport = createEmptyCloseReport();
+    let openCodeSnapshot = createEmptyOpenCodeSnapshot(scope.worktree);
+    let doctor = createDoctorState(config);
+    let recoveryMessage = null;
+    let controlPlane = null;
+    const getStatePath = () => {
+        if (config.persistence === false)
+            return null;
+        return config.persistence.path;
+    };
+    const load = async () => {
+        const path = getStatePath();
+        if (!path)
+            return;
+        try {
+            await access(path);
+        }
+        catch {
+            return;
+        }
+        try {
+            const raw = await readFile(path, "utf8");
+            const parsed = JSON.parse(raw);
+            workflow.stage = parsed.trace?.stage ?? "idle";
+            workflow.lastDecision = parsed.trace?.lastDecision;
+            workflow.recentEvents = parsed.trace?.recentEvents ?? [];
+            contextStats = normalizeContextStats(parsed.contextStats, config.maxMessages);
+            closeReport = normalizeCloseReport(parsed.closeReport);
+            openCodeSnapshot = normalizeOpenCodeSnapshot(parsed.openCodeSnapshot, scope.worktree);
+            doctor = normalizeDoctorState(parsed.doctor, config);
+            jobBoard.restore(parsed.jobBoard ?? {});
+            recoveryMessage = null;
+        }
+        catch {
+            recoveryMessage = "State file was corrupt and ignored.";
+            workflow.stage = "idle";
+            workflow.lastDecision = undefined;
+            workflow.recentEvents = [];
+            contextStats = createEmptyContextStats(config.maxMessages);
+            closeReport = createEmptyCloseReport();
+            openCodeSnapshot = createEmptyOpenCodeSnapshot(scope.worktree);
+            doctor = createDoctorState(config);
+            jobBoard.clear();
+        }
+    };
+    let saveLock = null;
+    const save = async () => {
+        const current = saveLock;
+        const promise = (async () => {
+            if (current)
+                await current;
+            const path = getStatePath();
+            if (!path)
+                return;
+            const state = {
+                version: 1,
+                trace: {
+                    stage: workflow.stage,
+                    lastDecision: workflow.lastDecision,
+                    recentEvents: workflow.recentEvents,
+                },
+                jobBoard: jobBoard.snapshot(),
+                contextStats,
+                closeReport,
+                openCodeSnapshot,
+                doctor,
+            };
+            const dir = dirname(path);
+            await mkdir(dir, { recursive: true });
+            await writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+        })();
+        saveLock = promise;
+        await promise;
+    };
+    const reset = async () => {
+        workflow.stage = "idle";
+        workflow.lastDecision = undefined;
+        workflow.recentEvents = [];
+        contextStats = createEmptyContextStats(config.maxMessages);
+        closeReport = createEmptyCloseReport();
+        openCodeSnapshot = createEmptyOpenCodeSnapshot(scope.worktree);
+        doctor = createDoctorState(config);
+        jobBoard.clear();
+        recordEvent("reset", "Runtime state reset.");
+        const path = getStatePath();
+        if (path) {
+            try {
+                await access(path);
+                await rm(path);
+            }
+            catch { /* ok */ }
+        }
+        await save();
+    };
+    const setMode = async (mode) => {
+        config.mode = mode;
+        recordEvent("command", `Mode set to ${mode}.`);
+        await save();
+    };
+    const setStage = (stage) => {
+        workflow.stage = stage;
+        recordEvent("stage", `Stage set to ${stage}.`);
+    };
+    const recordDecision = async (decision) => {
+        workflow.lastDecision = decision;
+        if (decision.bypassedByUser) {
+            recordEvent("bypass", `${decision.level}: ${decision.reason}`);
+        }
+        else if (decision.action === "block" || decision.action === "nudge") {
+            recordEvent("gate", `${decision.action} ${decision.level}: ${decision.reason}`);
+        }
+        await save();
+    };
+    const recordPruning = async (before, after) => {
+        if (after >= before)
+            return;
+        contextStats.maxMessages = config.maxMessages;
+        contextStats.lastBefore = before;
+        contextStats.lastAfter = after;
+        contextStats.lastPrunedAt = Date.now();
+        contextStats.totalPruned += before - after;
+        await save();
+    };
+    const refreshOpenCodeSnapshot = async (sessionID) => {
+        if (!controlPlane)
+            return;
+        const snapshot = await controlPlane.snapshot(sessionID);
+        openCodeSnapshot = {
+            pendingPermissions: snapshot.pendingPermissions,
+            todos: snapshot.todos,
+            diffSummary: snapshot.diffSummary,
+            worktree: snapshot.worktree === "unknown" ? scope.worktree : snapshot.worktree,
+            sessionStatus: snapshot.sessionStatus,
+            capabilities: snapshot.capabilities,
+            lastUpdatedAt: Date.now(),
+        };
+        if (snapshot.diffSummary !== "not collected") {
+            closeReport.behaviorChanges = appendUniqueLimited(closeReport.behaviorChanges, `Diff summary: ${snapshot.diffSummary}`, config.closeReport.maxItems);
+            closeReport.updatedAt = Date.now();
+        }
+        recordEvent("command", "OpenCode control-plane snapshot refreshed.");
+        await save();
+    };
+    const recordOpenCodeEvent = async (event) => {
+        const type = String(event.type ?? event.kind ?? "event");
+        const value = event.value;
+        if (type === "permission" || type === "permissions") {
+            openCodeSnapshot.pendingPermissions = Number(value ?? event.count ?? 0);
+        }
+        else if (type === "todo" || type === "todos") {
+            openCodeSnapshot.todos = Number(value ?? event.count ?? 0);
+        }
+        else if (type === "diff") {
+            openCodeSnapshot.diffSummary = String(value ?? event.summary ?? "available");
+        }
+        else if (type === "worktree") {
+            openCodeSnapshot.worktree = String(value ?? event.path ?? scope.worktree);
+        }
+        else if (type === "session") {
+            openCodeSnapshot.sessionStatus = String(value ?? event.status ?? "unknown");
+        }
+        else if (type === "capability") {
+            const capability = String(value ?? event.name ?? "");
+            if (capability && !openCodeSnapshot.capabilities.includes(capability)) {
+                openCodeSnapshot.capabilities.push(capability);
+            }
+        }
+        openCodeSnapshot.lastUpdatedAt = Date.now();
+        recordEvent("command", `OpenCode ${type} snapshot updated.`);
+        await save();
+    };
+    const recordToolEvidence = async (input, output) => {
+        if (!config.closeReport.autoCollect)
+            return;
+        const toolName = String(input.tool ?? input.name ?? input.toolID ?? "");
+        const args = (input.arguments ?? input.args ?? {});
+        const text = stringifyEvidence(output.output ?? output.result ?? output);
+        const command = String(args.command ?? args.cmd ?? "");
+        const max = config.closeReport.maxItems;
+        if (/bash|shell|terminal/i.test(toolName) && command) {
+            if (looksLikeTestCommand(command)) {
+                closeReport.testRuns = appendLimited(closeReport.testRuns, {
+                    command,
+                    result: looksLikeFailure(text) ? "fail" : "pass",
+                }, max);
+            }
+            if (/npm run verify|deno task verify|pnpm verify|yarn verify/.test(command)) {
+                closeReport.verificationResult = looksLikeFailure(text) ? "fail" : "pass";
+            }
+        }
+        if (/edit|write|patch/i.test(toolName)) {
+            const path = String(args.filePath ?? args.file ?? args.path ?? "");
+            if (path) {
+                closeReport.behaviorChanges = appendUniqueLimited(closeReport.behaviorChanges, `Touched ${path}`, max);
+            }
+        }
+        if (text && /delete|remove|simplif/i.test(text)) {
+            closeReport.deletions = appendUniqueLimited(closeReport.deletions, firstLine(text), max);
+        }
+        closeReport.updatedAt = Date.now();
+        await save();
+    };
+    const recordCloseEvidence = async (kind, payload) => {
+        const max = config.closeReport.maxItems;
+        const text = typeof payload === "string" ? payload.trim() : stringifyEvidence(payload).trim();
+        if (!text)
+            return;
+        if (kind === "behavior") {
+            closeReport.behaviorChanges = appendUniqueLimited(closeReport.behaviorChanges, text, max);
+        }
+        else if (kind === "risk") {
+            closeReport.remainingRisks = appendUniqueLimited(closeReport.remainingRisks, text, max);
+        }
+        else if (kind === "deletion") {
+            closeReport.deletions = appendUniqueLimited(closeReport.deletions, text, max);
+        }
+        else if (kind === "verification") {
+            if (text === "pass" || text === "fail" || text === "pending") {
+                closeReport.verificationResult = text;
+            }
+        }
+        else if (kind === "test") {
+            closeReport.testRuns = appendLimited(closeReport.testRuns, {
+                command: text,
+                result: "unknown",
+            }, max);
+        }
+        closeReport.updatedAt = Date.now();
+        await save();
+    };
+    const recordEvent = (type, summary) => {
+        workflow.recentEvents.push({ ts: Date.now(), type, summary });
+        workflow.recentEvents = workflow.recentEvents.slice(-50);
+    };
+    const formatStatus = (sessionID = "") => {
+        const lines = ["LazyOpenCode Governed Team Runtime", ""];
+        lines.push(`Mode: ${config.mode}`);
+        lines.push(`Stage: ${workflow.stage}`);
+        lines.push(`Persistence: ${config.persistence === false ? "off" : config.persistence.path}`);
+        if (recoveryMessage)
+            lines.push(`Recovery: ${recoveryMessage}`);
+        if (workflow.lastDecision) {
+            const d = workflow.lastDecision;
+            lines.push(`Last decision: ${d.action} ${d.level} — ${d.reason}`);
+        }
+        lines.push("", formatInstallHealth());
+        lines.push("", formatTokenControl(contextStats));
+        lines.push("", formatOpenCodeSnapshot(openCodeSnapshot));
+        const board = sessionID ? jobBoard.formatForPrompt(sessionID) : null;
+        lines.push("", board ?? "[Background Job Board]\n  No jobs for this session.");
+        if (workflow.recentEvents.length > 0) {
+            lines.push("", "Recent gate decisions:");
+            for (const event of workflow.recentEvents.slice(-8)) {
+                lines.push(`- ${event.type}: ${event.summary}`);
+            }
+        }
+        else {
+            lines.push("", "Recent gate decisions: none");
+        }
+        return lines.join("\n");
+    };
+    const formatIsolationAdvice = (decision = workflow.lastDecision) => {
+        if (!decision)
+            return null;
+        if (config.opencode.worktreeIsolation === "off")
+            return null;
+        const risky = decision.level === "high_risk" || decision.level === "ambiguous";
+        if (config.opencode.worktreeIsolation === "risky-only" && !risky)
+            return null;
+        const hasWorktree = openCodeSnapshot.capabilities.includes("worktree") ||
+            openCodeSnapshot.capabilities.includes("projectWorktree");
+        const hasRevert = openCodeSnapshot.capabilities.includes("revert") ||
+            openCodeSnapshot.capabilities.includes("revertCheckpoint");
+        return [
+            "Workspace isolation",
+            hasWorktree
+                ? "- available: use isolated OpenCode worktree/project copy before build"
+                : "- degraded: OpenCode worktree/project-copy capability not detected",
+            hasRevert ? "- revert checkpoints: available" : "- revert checkpoints: not detected",
+            "- policy: isolate high-risk or ambiguous work before implementation",
+        ].join("\n");
+    };
+    const formatCloseReport = (sessionID = "") => {
+        const running = sessionID ? jobBoard.getRunningJobs(sessionID) : [];
+        const terminal = sessionID ? jobBoard.getTerminalUnreconciledJobs(sessionID) : [];
+        const reusable = sessionID ? jobBoard.getReusableJobs(sessionID) : [];
+        const stale = sessionID ? jobBoard.getStaleJobs(sessionID) : [];
+        const decision = workflow.lastDecision;
+        return [
+            "LAZY CLOSE REPORT",
+            terminal.length > 0
+                ? "Close blocked: reconcile terminal jobs first."
+                : "Close ready: no terminal unreconciled jobs.",
+            "",
+            "Workflow",
+            `- Stage: ${workflow.stage}`,
+            `- Last decision: ${decision ? `${decision.action} ${decision.level} - ${decision.reason}` : "none"}`,
+            "",
+            "Job summary",
+            `- Running jobs: ${running.length}`,
+            `- Terminal unreconciled jobs: ${terminal.length}`,
+            `- Reusable sessions: ${reusable.length}`,
+            `- Stale sessions: ${stale.length}`,
+            "",
+            "Changed behavior",
+            ...formatStringList(closeReport.behaviorChanges),
+            "Tests run",
+            ...formatTestRuns(closeReport.testRuns),
+            `Verification result: ${closeReport.verificationResult ?? "pending"}`,
+            `Terminal jobs reconciled: ${terminal.length === 0 ? "yes" : "no"}`,
+            "Remaining risks",
+            ...formatStringList(closeReport.remainingRisks),
+            "Simplifications/deletions",
+            ...formatStringList(closeReport.deletions),
+        ].join("\n");
+    };
+    const formatInstallHealth = () => {
+        return [
+            "Install health",
+            "- agents registered: 8 lazy agents",
+            "- skills path registered: yes",
+            `- council: ${config.council.enabled ? config.council.eligibility : "disabled"}`,
+            `- permission guard: ${config.permissionGuard ? "enabled" : "disabled"}`,
+            `- token control: maxMessages ${config.maxMessages}`,
+            `- sdk: ${config.sdk.mode} + legacy hooks ${config.sdk.legacyHookAdapter ? "enabled" : "disabled"}`,
+        ].join("\n");
+    };
+    const formatDoctorReport = () => {
+        const skillsDir = getSkillsDir();
+        const distDir = dirname(fileURLToPath(import.meta.url));
+        const pluginPackageJson = findUp("package.json", distDir);
+        const staleAgents = ["orchestrator", "council-master"].filter((name) => existsSync(join(distDir, "..", "agents", `${name}.js`)) ||
+            existsSync(join(distDir, "..", "agents", `${name}.d.ts`)));
+        doctor = {
+            ...doctor,
+            v2Registration: config.sdk.mode === "v2",
+            legacyHookAdapter: config.sdk.legacyHookAdapter,
+            skills: existsSync(skillsDir),
+            commands: config.commands.lazy,
+            packageReady: pluginPackageJson !== null,
+            desktopConfig: findUp(join("apps", "lazyopencode-desktop", "lazyopencode.default.jsonc"), distDir) !==
+                null,
+            lastCheckedAt: Date.now(),
+        };
+        const warnings = [...doctor.warnings];
+        if (!config.sdk.legacyHookAdapter)
+            warnings.push("legacy hook adapter disabled");
+        if (!doctor.skills)
+            warnings.push(`skills path missing: ${skillsDir}`);
+        if (!doctor.packageReady)
+            warnings.push("plugin package.json not found");
+        if (staleAgents.length > 0)
+            warnings.push(`stale agent files: ${staleAgents.join(", ")}`);
+        if (config.council.enabled && config.council.eligibility === "always") {
+            warnings.push("council eligibility is always; guarded escalation is disabled");
+        }
+        return [
+            "LAZY DOCTOR",
+            `- v2 registration: ${doctor.v2Registration ? "ok" : "missing"}`,
+            `- legacy hooks: ${doctor.legacyHookAdapter ? "ok" : "disabled"}`,
+            `- skills: ${doctor.skills ? "ok" : "missing"}`,
+            `- commands: ${doctor.commands ? "ok" : "disabled"}`,
+            `- permissions: ${config.permissionGuard ? "guarded" : "unguarded"}`,
+            `- package: ${doctor.packageReady ? "ready" : "unknown"}`,
+            `- desktop config: ${doctor.desktopConfig ? "detected" : "not detected"}`,
+            `- warnings: ${warnings.length === 0 ? "none" : warnings.join("; ")}`,
+        ].join("\n");
+    };
+    return {
+        get config() {
+            return config;
+        },
+        get scope() {
+            return scope;
+        },
+        get jobBoard() {
+            return jobBoard;
+        },
+        get sessionAgentMap() {
+            return sessionAgentMap;
+        },
+        get sessionDepth() {
+            return sessionDepth;
+        },
+        get workflow() {
+            return workflow;
+        },
+        get contextStats() {
+            return contextStats;
+        },
+        get closeReport() {
+            return closeReport;
+        },
+        get openCodeSnapshot() {
+            return openCodeSnapshot;
+        },
+        get doctor() {
+            return doctor;
+        },
+        get recoveryMessage() {
+            return recoveryMessage;
+        },
+        setControlPlane: (next) => {
+            controlPlane = next;
+        },
+        configure: (input) => {
+            Object.assign(config, resolveLazyConfig(input, scope));
+            contextStats.maxMessages = config.maxMessages;
+            doctor = createDoctorState(config);
+            jobBoard.configure({
+                maxReusablePerAgent: config.maxSessionsPerAgent,
+            });
+        },
+        load,
+        save,
+        reset,
+        setMode,
+        setStage,
+        recordDecision,
+        recordPruning,
+        refreshOpenCodeSnapshot,
+        recordOpenCodeEvent,
+        recordToolEvidence,
+        recordCloseEvidence,
+        recordEvent,
+        formatIsolationAdvice,
+        formatStatus,
+        formatCloseReport,
+        formatInstallHealth,
+        formatDoctorReport,
+        getReferenceSnapshot: () => ({
+            scope,
+            workflow,
+            contextStats,
+            closeReport,
+            openCodeSnapshot,
+            doctor,
+        }),
+    };
+}
+export function resolveLazyConfig(input, scope) {
+    const persistence = input?.persistence === false ? false : {
+        path: input?.persistence?.path ??
+            join(homedir() || tmpdir(), ".lazyopencode", "state", `${scope.scopeID}.json`),
+    };
+    return {
+        sdk: {
+            mode: "v2",
+            legacyHookAdapter: input?.sdk?.legacyHookAdapter ?? true,
+        },
+        takeover: input?.takeover ?? "governed",
+        opencode: {
+            sessionStatus: input?.opencode?.sessionStatus ?? true,
+            vcsDiff: input?.opencode?.vcsDiff ?? true,
+            todos: input?.opencode?.todos ?? true,
+            permissions: input?.opencode?.permissions ?? true,
+            worktreeIsolation: input?.opencode?.worktreeIsolation ?? "risky-only",
+            revertCheckpoints: input?.opencode?.revertCheckpoints ?? true,
+        },
+        closeReport: {
+            autoCollect: input?.closeReport?.autoCollect ?? true,
+            maxItems: input?.closeReport?.maxItems ?? 5,
+        },
+        mode: input?.mode ?? "governor",
+        maxSessionsPerAgent: input?.maxSessionsPerAgent ?? 2,
+        maxActiveTaskDepth: input?.maxActiveTaskDepth ?? 4,
+        maxMessages: input?.maxMessages ?? 80,
+        permissionGuard: input?.permissionGuard ?? true,
+        persistence,
+        workflowGate: input?.workflowGate ?? true,
+        ponytailMode: input?.ponytailMode ?? true,
+        commands: {
+            lazy: input?.commands?.lazy ?? true,
+            deepworkAlias: input?.commands?.deepworkAlias ?? true,
+        },
+        council: defaultCouncilConfig(input?.council),
+    };
+}
+/** ponytail: simple string hash for scope isolation, not crypto. Upgrade: crypto.subtle when scopeID used for security. */
+function hashScopeID(input) {
+    let h = 0;
+    for (let i = 0; i < input.length; i++) {
+        h = ((h << 5) - h + input.charCodeAt(i)) | 0;
+    }
+    return (h >>> 0).toString(16).padStart(8, "0");
+}
+function createScope(ctx) {
+    const projectRoot = ctx.project?.root ?? ctx.directory ?? process.cwd();
+    const worktree = ctx.worktree ?? ctx.project?.worktree ?? ctx.directory ?? projectRoot;
+    const scopeID = hashScopeID(`${projectRoot}::${worktree}`);
+    return { projectRoot, worktree, scopeID };
+}
+function createEmptyTrace() {
+    return { stage: "idle", recentEvents: [] };
+}
+function createEmptyContextStats(maxMessages) {
+    return { maxMessages, totalPruned: 0 };
+}
+function createEmptyCloseReport() {
+    return {
+        behaviorChanges: [],
+        testRuns: [],
+        remainingRisks: [],
+        deletions: [],
+    };
+}
+function createEmptyOpenCodeSnapshot(worktree) {
+    return {
+        pendingPermissions: 0,
+        todos: 0,
+        diffSummary: "not collected",
+        worktree,
+        sessionStatus: "unknown",
+        capabilities: [],
+    };
+}
+function createDoctorState(config) {
+    return {
+        v2Registration: config.sdk.mode === "v2",
+        legacyHookAdapter: config.sdk.legacyHookAdapter,
+        skills: true,
+        commands: config.commands.lazy,
+        desktopConfig: false,
+        packageReady: true,
+        warnings: [],
+    };
+}
+function normalizeContextStats(input, maxMessages) {
+    return {
+        maxMessages: input?.maxMessages ?? maxMessages,
+        lastBefore: input?.lastBefore,
+        lastAfter: input?.lastAfter,
+        lastPrunedAt: input?.lastPrunedAt,
+        totalPruned: input?.totalPruned ?? 0,
+    };
+}
+function normalizeCloseReport(input) {
+    return {
+        behaviorChanges: input?.behaviorChanges ?? [],
+        testRuns: input?.testRuns ?? [],
+        verificationResult: input?.verificationResult,
+        remainingRisks: input?.remainingRisks ?? [],
+        deletions: input?.deletions ?? [],
+        updatedAt: input?.updatedAt,
+    };
+}
+function normalizeOpenCodeSnapshot(input, worktree) {
+    return {
+        pendingPermissions: input?.pendingPermissions ?? 0,
+        todos: input?.todos ?? 0,
+        diffSummary: input?.diffSummary ?? "not collected",
+        worktree: input?.worktree ?? worktree,
+        sessionStatus: input?.sessionStatus ?? "unknown",
+        capabilities: input?.capabilities ?? [],
+        lastUpdatedAt: input?.lastUpdatedAt,
+    };
+}
+function normalizeDoctorState(input, config) {
+    return {
+        ...createDoctorState(config),
+        ...input,
+        warnings: input?.warnings ?? [],
+    };
+}
+function formatTokenControl(stats) {
+    const lastPrune = stats.lastBefore !== undefined && stats.lastAfter !== undefined
+        ? `${stats.lastBefore} -> ${stats.lastAfter}`
+        : "none";
+    return [
+        "Token control",
+        `- maxMessages: ${stats.maxMessages}`,
+        `- last prune: ${lastPrune}`,
+        `- total pruned: ${stats.totalPruned}`,
+        "- job board mode: full when dirty, mini when clean",
+    ].join("\n");
+}
+function formatOpenCodeSnapshot(snapshot) {
+    return [
+        "OpenCode",
+        `- session: ${snapshot.sessionStatus}`,
+        `- pending permissions: ${snapshot.pendingPermissions}`,
+        `- todos: ${snapshot.todos}`,
+        `- diff: ${snapshot.diffSummary}`,
+        `- worktree: ${snapshot.worktree}`,
+        `- capabilities: ${snapshot.capabilities.length > 0 ? snapshot.capabilities.join(", ") : "not collected"}`,
+    ].join("\n");
+}
+function findUp(filename, startDir) {
+    let current = startDir;
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(current, filename);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function formatStringList(items) {
+    if (items.length === 0)
+        return ["- none recorded"];
+    return items.map((item) => `- ${item}`);
+}
+function formatTestRuns(items) {
+    if (items.length === 0)
+        return ["- none recorded"];
+    return items.map((item) => `- ${item.command}: ${item.result}`);
+}
+function appendLimited(items, item, max) {
+    return [...items, item].slice(-Math.max(1, max));
+}
+function appendUniqueLimited(items, item, max) {
+    return appendLimited(items.filter((existing) => existing !== item), item, max);
+}
+function stringifyEvidence(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function looksLikeTestCommand(command) {
+    return /\b(test|check|verify|lint|fmt)\b/.test(command);
+}
+function looksLikeFailure(text) {
+    return /\b(error|failed|failure|exception|not ok)\b/i.test(text);
+}
+function firstLine(text) {
+    return text.split(/\r?\n/).find((line) => line.trim())?.trim() ?? text.trim();
+}

package/dist/hooks/session-events.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Session lifecycle hooks — cleanup, reconciliation, and state tracking.
+ *
+ * ponytail: minimal lifecycle. Only track what affects job board integrity.
+ */
+import type { LazyRuntime } from "./runtime.js";
+/**
+ * Combined session event hook — dispatches on event.type.
+ * SDK only supports "event" as a single hook, not per-event-type hooks.
+ */
+export declare function createSessionEventsHook(rememberFn: (sid: string) => string[], runtime?: LazyRuntime): (input: {
+    event: {
+        type: string;
+        properties?: Record<string, unknown>;
+    };
+}) => Promise<void>;