@claude-flow/cli 3.64.0 → 3.65.0

package/dist/src/mods/command-registry/schema.d.ts

@@ -63,19 +63,19 @@ export declare const commandDefinitionSchema: z.ZodEffects<z.ZodObject<{
         path: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         path: string;
-        repository: string;
         commit: string;
+        repository: string;
     }, {
         path: string;
-        repository: string;
         commit: string;
+        repository: string;
     }>;
 }, "strict", z.ZodTypeAny, {
     id: string;
     source: {
         path: string;
-        repository: string;
         commit: string;
+        repository: string;
     };
     schemaVersion: 1;
     kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -100,8 +100,8 @@ export declare const commandDefinitionSchema: z.ZodEffects<z.ZodObject<{
     id: string;
     source: {
         path: string;
-        repository: string;
         commit: string;
+        repository: string;
     };
     schemaVersion: 1;
     kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -126,8 +126,8 @@ export declare const commandDefinitionSchema: z.ZodEffects<z.ZodObject<{
     id: string;
     source: {
         path: string;
-        repository: string;
         commit: string;
+        repository: string;
     };
     schemaVersion: 1;
     kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -152,8 +152,8 @@ export declare const commandDefinitionSchema: z.ZodEffects<z.ZodObject<{
     id: string;
     source: {
         path: string;
-        repository: string;
         commit: string;
+        repository: string;
     };
     schemaVersion: 1;
     kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -190,18 +190,18 @@ export declare const inventorySourceSchema: z.ZodObject<{
     initCategory: z.ZodOptional<z.ZodString>;
     shippedIn: z.ZodArray<z.ZodString, "many">;
 }, "strict", z.ZodTypeAny, {
+    digest: string;
     sourcePath: string;
     channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-    digest: string;
     package: string;
     observedInvocation: string;
     binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
     shippedIn: string[];
     initCategory?: string | undefined;
 }, {
+    digest: string;
     sourcePath: string;
     channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-    digest: string;
     package: string;
     observedInvocation: string;
     binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -244,19 +244,19 @@ export declare const catalogEntrySchema: z.ZodObject<{
             path: z.ZodString;
         }, "strict", z.ZodTypeAny, {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         }, {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         }>;
     }, "strict", z.ZodTypeAny, {
         id: string;
         source: {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         };
         schemaVersion: 1;
         kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -281,8 +281,8 @@ export declare const catalogEntrySchema: z.ZodObject<{
         id: string;
         source: {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         };
         schemaVersion: 1;
         kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -307,8 +307,8 @@ export declare const catalogEntrySchema: z.ZodObject<{
         id: string;
         source: {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         };
         schemaVersion: 1;
         kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -333,8 +333,8 @@ export declare const catalogEntrySchema: z.ZodObject<{
         id: string;
         source: {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         };
         schemaVersion: 1;
         kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -368,18 +368,18 @@ export declare const catalogEntrySchema: z.ZodObject<{
         initCategory: z.ZodOptional<z.ZodString>;
         shippedIn: z.ZodArray<z.ZodString, "many">;
     }, "strict", z.ZodTypeAny, {
+        digest: string;
         sourcePath: string;
         channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-        digest: string;
         package: string;
         observedInvocation: string;
         binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
         shippedIn: string[];
         initCategory?: string | undefined;
     }, {
+        digest: string;
         sourcePath: string;
         channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-        digest: string;
         package: string;
         observedInvocation: string;
         binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -389,9 +389,9 @@ export declare const catalogEntrySchema: z.ZodObject<{
     notes: z.ZodArray<z.ZodString, "many">;
 }, "strict", z.ZodTypeAny, {
     sources: {
+        digest: string;
         sourcePath: string;
         channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-        digest: string;
         package: string;
         observedInvocation: string;
         binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -404,8 +404,8 @@ export declare const catalogEntrySchema: z.ZodObject<{
         id: string;
         source: {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         };
         schemaVersion: 1;
         kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -430,9 +430,9 @@ export declare const catalogEntrySchema: z.ZodObject<{
     notes: string[];
 }, {
     sources: {
+        digest: string;
         sourcePath: string;
         channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-        digest: string;
         package: string;
         observedInvocation: string;
         binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -445,8 +445,8 @@ export declare const catalogEntrySchema: z.ZodObject<{
         id: string;
         source: {
             path: string;
-            repository: string;
             commit: string;
+            repository: string;
         };
         schemaVersion: 1;
         kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -510,19 +510,19 @@ export declare const commandCatalogSchema: z.ZodObject<{
                 path: z.ZodString;
             }, "strict", z.ZodTypeAny, {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             }, {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             }>;
         }, "strict", z.ZodTypeAny, {
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -547,8 +547,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -573,8 +573,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -599,8 +599,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -634,18 +634,18 @@ export declare const commandCatalogSchema: z.ZodObject<{
             initCategory: z.ZodOptional<z.ZodString>;
             shippedIn: z.ZodArray<z.ZodString, "many">;
         }, "strict", z.ZodTypeAny, {
+            digest: string;
             sourcePath: string;
             channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-            digest: string;
             package: string;
             observedInvocation: string;
             binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
             shippedIn: string[];
             initCategory?: string | undefined;
         }, {
+            digest: string;
             sourcePath: string;
             channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-            digest: string;
             package: string;
             observedInvocation: string;
             binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -655,9 +655,9 @@ export declare const commandCatalogSchema: z.ZodObject<{
         notes: z.ZodArray<z.ZodString, "many">;
     }, "strict", z.ZodTypeAny, {
         sources: {
+            digest: string;
             sourcePath: string;
             channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-            digest: string;
             package: string;
             observedInvocation: string;
             binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -670,8 +670,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -696,9 +696,9 @@ export declare const commandCatalogSchema: z.ZodObject<{
         notes: string[];
     }, {
         sources: {
+            digest: string;
             sourcePath: string;
             channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-            digest: string;
             package: string;
             observedInvocation: string;
             binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -711,8 +711,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -739,9 +739,9 @@ export declare const commandCatalogSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     entries: {
         sources: {
+            digest: string;
             sourcePath: string;
             channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-            digest: string;
             package: string;
             observedInvocation: string;
             binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -754,8 +754,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";
@@ -785,9 +785,9 @@ export declare const commandCatalogSchema: z.ZodObject<{
 }, {
     entries: {
         sources: {
+            digest: string;
             sourcePath: string;
             channel: "repo-project-commands" | "cli-init-template" | "marketplace-plugin" | "source-plugin" | "mod-registration";
-            digest: string;
             package: string;
             observedInvocation: string;
             binding: "markdown-loader" | "mod-register" | "mod-middleware-on-markdown";
@@ -800,8 +800,8 @@ export declare const commandCatalogSchema: z.ZodObject<{
             id: string;
             source: {
                 path: string;
-                repository: string;
                 commit: string;
+                repository: string;
             };
             schemaVersion: 1;
             kind: "help" | "query" | "prompt" | "workflow" | "mutation";

package/dist/src/mods/compact-snapshots.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ADR-505: `ruflo doctor` check for ruflo-mods compaction snapshots.
+ *
+ * The `compactSnapshot` option (default on) writes conversation text to
+ * `.claude-flow/sessions/compactions/`. `ruflo init` gitignores it through
+ * `.claude-flow/.gitignore` (`sessions/`); a project whose ignore rules lost
+ * that would commit transcripts. Warn-only: when snapshots exist and git does
+ * not ignore them. No snapshots, or not a git work tree, is a pass.
+ */
+export declare const COMPACTIONS_DIR = ".claude-flow/sessions/compactions";
+export type SnapshotHealth = {
+    status: 'pass' | 'warn';
+    message: string;
+    fix?: string;
+};
+/** `ignored`: git ignores the path; `not-ignored`: it would be committed; `no-git`: not a work tree or git missing. */
+export type IgnoreState = 'ignored' | 'not-ignored' | 'no-git';
+/** `git check-ignore -q`: exit 0 ignored, 1 not ignored, anything else (128: not a repo; ENOENT: no git) no answer. */
+export declare function gitIgnoreState(root: string, relPath: string): IgnoreState;
+export declare function compactSnapshotHealth(root: string, ignoreState?: (root: string, relPath: string) => IgnoreState): SnapshotHealth;
+//# sourceMappingURL=compact-snapshots.d.ts.map

package/dist/src/mods/compact-snapshots.js

@@ -0,0 +1,45 @@
+/**
+ * ADR-505: `ruflo doctor` check for ruflo-mods compaction snapshots.
+ *
+ * The `compactSnapshot` option (default on) writes conversation text to
+ * `.claude-flow/sessions/compactions/`. `ruflo init` gitignores it through
+ * `.claude-flow/.gitignore` (`sessions/`); a project whose ignore rules lost
+ * that would commit transcripts. Warn-only: when snapshots exist and git does
+ * not ignore them. No snapshots, or not a git work tree, is a pass.
+ */
+import { execFileSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const COMPACTIONS_DIR = '.claude-flow/sessions/compactions';
+/** `git check-ignore -q`: exit 0 ignored, 1 not ignored, anything else (128: not a repo; ENOENT: no git) no answer. */
+export function gitIgnoreState(root, relPath) {
+    try {
+        execFileSync('git', ['check-ignore', '-q', '--', relPath], { cwd: root, stdio: 'ignore', timeout: 5000 });
+        return 'ignored';
+    }
+    catch (error) {
+        return error.status === 1 ? 'not-ignored' : 'no-git';
+    }
+}
+export function compactSnapshotHealth(root, ignoreState = gitIgnoreState) {
+    let files;
+    try {
+        files = readdirSync(join(root, COMPACTIONS_DIR)).filter((name) => name.endsWith('.jsonl'));
+    }
+    catch {
+        files = [];
+    }
+    if (files.length === 0)
+        return { status: 'pass', message: 'no compaction snapshots in this project' };
+    const sample = `${COMPACTIONS_DIR}/${files.sort()[0]}`;
+    const state = ignoreState(root, sample);
+    if (state === 'not-ignored') {
+        return {
+            status: 'warn',
+            message: `${files.length} compaction snapshot(s) in ${COMPACTIONS_DIR}/ hold conversation text and git does not ignore them`,
+            fix: 'add .claude-flow/ (or .claude-flow/sessions/) to .gitignore, or set the ruflo-mods compactSnapshot option to false',
+        };
+    }
+    return { status: 'pass', message: `${files.length} compaction snapshot(s), ${state === 'ignored' ? 'ignored by git' : 'not in a git work tree'}` };
+}
+//# sourceMappingURL=compact-snapshots.js.map

package/dist/src/mods/headless-check.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ADR-510 §2.4 — `ruflo doctor --component headless-plugins`: do ruflo mods
+ * actually run under `claude -p` on this machine?
+ *
+ * Runs `claude -p --plugin-dir <ruflo-mods> --output-format stream-json
+ * --verbose "reply ok"` in a throwaway project that has a `.claude-flow/`
+ * directory, then reports:
+ *   - whether the init event lists ruflo-mods from that folder;
+ *   - whether `plugin_errors` is empty (Claude Code omits the key when none);
+ *   - whether the mod's session heartbeat (`.claude-flow/mods/session.json`)
+ *     was written — the proof that its function hooks ran.
+ *
+ * The runner is injectable so tests never spawn `claude` or need a key.
+ * Without any model credential the check is skipped (warn), never spawned.
+ */
+import { type PluginPaths } from './plugin-paths.js';
+export declare const HEADLESS_TIMEOUT_MS = 60000;
+export declare const HEARTBEAT: string;
+export interface HeadlessRun {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export type HeadlessRunner = (argv: string[], env: NodeJS.ProcessEnv, cwd: string, timeoutMs: number) => Promise<HeadlessRun>;
+export interface HeadlessCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    message: string;
+    fix?: string;
+}
+export interface HeadlessCheckDeps {
+    runner?: HeadlessRunner;
+    resolve?: () => PluginPaths;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    /** Throwaway project dir factory (must be removable afterwards). */
+    makeProject?: () => string;
+    exists?: (path: string) => boolean;
+    timeoutMs?: number;
+    model?: string;
+}
+export declare const spawnHeadless: HeadlessRunner;
+/** A model credential Claude Code could use; without one the check would only fail on auth. */
+export declare function hasModelCredential(env: NodeJS.ProcessEnv, configDir: string, exists?: (p: string) => boolean): boolean;
+interface InitEvent {
+    plugins?: Array<{
+        name?: string;
+        path?: string;
+        source?: string;
+    }>;
+    plugin_errors?: unknown[];
+}
+/** The `system/init` event of a stream-json run, if any. */
+export declare function findInitEvent(stdout: string): InitEvent | null;
+export declare function checkHeadlessPlugins(deps?: HeadlessCheckDeps): Promise<HeadlessCheck>;
+export {};
+//# sourceMappingURL=headless-check.d.ts.map

package/dist/src/mods/headless-check.js

@@ -0,0 +1,137 @@
+/**
+ * ADR-510 §2.4 — `ruflo doctor --component headless-plugins`: do ruflo mods
+ * actually run under `claude -p` on this machine?
+ *
+ * Runs `claude -p --plugin-dir <ruflo-mods> --output-format stream-json
+ * --verbose "reply ok"` in a throwaway project that has a `.claude-flow/`
+ * directory, then reports:
+ *   - whether the init event lists ruflo-mods from that folder;
+ *   - whether `plugin_errors` is empty (Claude Code omits the key when none);
+ *   - whether the mod's session heartbeat (`.claude-flow/mods/session.json`)
+ *     was written — the proof that its function hooks ran.
+ *
+ * The runner is injectable so tests never spawn `claude` or need a key.
+ * Without any model credential the check is skipped (warn), never spawned.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { ENABLE_ENV } from './install.js';
+import { claudeConfigDir } from './plugin-resolve.js';
+import { resolvePluginPaths } from './plugin-paths.js';
+export const HEADLESS_TIMEOUT_MS = 60_000;
+export const HEARTBEAT = join('.claude-flow', 'mods', 'session.json');
+const PLUGIN = 'ruflo-mods';
+const NAME = 'Headless plugins (ADR-510)';
+export const spawnHeadless = (argv, env, cwd, timeoutMs) => new Promise((done) => {
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let child;
+    try {
+        child = spawn('claude', argv, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    }
+    catch (e) {
+        done({ exitCode: null, stdout: '', stderr: e instanceof Error ? e.message : String(e) });
+        return;
+    }
+    const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* already gone */ }
+    }, timeoutMs);
+    child.stdout?.on('data', (d) => { stdout += d.toString(); });
+    child.stderr?.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (e) => { clearTimeout(timer); done({ exitCode: null, stdout, stderr: e.message, timedOut }); });
+    child.on('close', (code) => { clearTimeout(timer); done({ exitCode: code, stdout, stderr, timedOut }); });
+});
+/** A model credential Claude Code could use; without one the check would only fail on auth. */
+export function hasModelCredential(env, configDir, exists = existsSync) {
+    const keys = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX'];
+    if (keys.some((k) => !!env[k]))
+        return true;
+    // macOS keeps the login in the keychain, which we cannot see from here.
+    if (process.platform === 'darwin')
+        return true;
+    return exists(join(configDir, '.credentials.json'));
+}
+/** The `system/init` event of a stream-json run, if any. */
+export function findInitEvent(stdout) {
+    for (const line of stdout.split('\n')) {
+        const t = line.trim();
+        if (!t.startsWith('{'))
+            continue;
+        try {
+            const ev = JSON.parse(t);
+            if (ev.type === 'system' && ev.subtype === 'init')
+                return ev;
+        }
+        catch {
+            // not a JSON line
+        }
+    }
+    return null;
+}
+const canonical = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+};
+export async function checkHeadlessPlugins(deps = {}) {
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? existsSync;
+    const paths = (deps.resolve ?? (() => resolvePluginPaths([PLUGIN], { env, home: deps.home })))();
+    const mods = paths.resolved.find((p) => p.name === PLUGIN);
+    if (!mods) {
+        const why = paths.missing.find((m) => m.name === PLUGIN)?.reason ?? 'not found';
+        return { name: NAME, status: 'warn', message: `${PLUGIN} not found (${why}); headless workers run without it`, fix: 'ruflo mods install' };
+    }
+    const configDir = claudeConfigDir(env, deps.home ?? homedir());
+    if (!deps.runner && !hasModelCredential(env, configDir, exists)) {
+        return { name: NAME, status: 'warn', message: `skipped: no model credential for claude -p (${PLUGIN} resolves to ${mods.path})`, fix: 'set ANTHROPIC_API_KEY or run `claude login`, then re-run' };
+    }
+    const project = (deps.makeProject ?? (() => mkdtempSync(join(tmpdir(), 'ruflo-headless-'))))();
+    try {
+        mkdirSync(join(project, '.claude-flow'), { recursive: true });
+        const argv = ['-p', 'reply ok', '--plugin-dir', mods.path, '--output-format', 'stream-json', '--verbose', '--model', deps.model ?? 'haiku'];
+        const runEnv = { ...env, CLAUDE_ENTRYPOINT: 'worker' };
+        if (runEnv[ENABLE_ENV] === undefined)
+            runEnv[ENABLE_ENV] = '1';
+        delete runEnv.CLAUDE_SESSION_ID;
+        delete runEnv.CLAUDE_PARENT_SESSION_ID;
+        const run = await (deps.runner ?? spawnHeadless)(argv, runEnv, project, deps.timeoutMs ?? HEADLESS_TIMEOUT_MS);
+        if (run.timedOut) {
+            return { name: NAME, status: 'fail', message: `claude -p did not finish in ${(deps.timeoutMs ?? HEADLESS_TIMEOUT_MS) / 1000}s` };
+        }
+        const init = findInitEvent(run.stdout);
+        if (!init) {
+            const tail = (run.stderr || run.stdout).trim().split('\n').slice(-1)[0] ?? '';
+            return { name: NAME, status: 'fail', message: `no init event from claude -p (exit ${run.exitCode})${tail ? `: ${tail.slice(0, 200)}` : ''}`, fix: 'ruflo doctor -c claude' };
+        }
+        const want = canonical(mods.path);
+        const listed = (init.plugins ?? []).some((p) => p.name === PLUGIN && typeof p.path === 'string' && canonical(p.path) === want);
+        const errors = Array.isArray(init.plugin_errors) ? init.plugin_errors : [];
+        const heartbeat = exists(join(project, HEARTBEAT));
+        const facts = `init lists ${PLUGIN}: ${listed ? 'yes' : 'no'}; plugin_errors: ${errors.length === 0 ? 'none' : JSON.stringify(errors).slice(0, 200)}; heartbeat: ${heartbeat ? 'written' : 'absent'}`;
+        if (!listed || errors.length > 0) {
+            return { name: NAME, status: 'fail', message: `${facts} (${mods.path})`, fix: `claude -p --plugin-dir ${JSON.stringify(mods.path)} --output-format stream-json --verbose "reply ok"` };
+        }
+        if (!heartbeat) {
+            return { name: NAME, status: 'warn', message: `${facts}: the plugin loads but its function hooks did not run (Claude Code too old, or ${ENABLE_ENV}=0)` };
+        }
+        return { name: NAME, status: 'pass', message: `${facts} (${mods.source}: ${mods.path})` };
+    }
+    finally {
+        try {
+            rmSync(project, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+//# sourceMappingURL=headless-check.js.map

package/dist/src/mods/headless-plugins.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ADR-510 §2.2 — give a headless `claude -p` worker its ruflo plugins.
+ *
+ * Every place ruflo builds a `claude -p` command line passes its argv and env
+ * through `withHeadlessPlugins`. It appends `--plugin-dir <path>` per plugin
+ * in the worker profile (default: ruflo-mods) and sets
+ * `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` unless the caller set it (a caller's
+ * `0` stays `0`). A caller's own `--plugin-dir` for the same plugin is never
+ * duplicated.
+ *
+ * A plugin that cannot be resolved does not stop the worker: it is logged once
+ * per process ("plugin <name> not found; worker runs without it") and returned
+ * in `missing` for the worker's status.
+ *
+ * Profile override: `RUFLO_HEADLESS_PLUGINS` is a comma list of plugin names;
+ * `none` (or an empty value) turns plugin loading off.
+ */
+import { type ResolveOptions, type PluginPaths } from './plugin-paths.js';
+export declare const DEFAULT_WORKER_PLUGINS: readonly string[];
+export declare const PROFILE_ENV = "RUFLO_HEADLESS_PLUGINS";
+export interface HeadlessPluginOptions extends ResolveOptions {
+    /** Plugin names to load; defaults to the env profile, else DEFAULT_WORKER_PLUGINS. */
+    profile?: readonly string[];
+    /** Where the once-per-process warning goes (default: stderr). */
+    warn?: (line: string) => void;
+    /** Injectable resolver, for tests. */
+    resolver?: (names: readonly string[], opts: ResolveOptions) => PluginPaths;
+}
+export interface HeadlessPluginResult<E> {
+    argv: string[];
+    env: E;
+    /** Plugins loaded via --plugin-dir by this call (not the caller's own). */
+    added: string[];
+    /** Plugins in the profile that could not be resolved. */
+    missing: string[];
+}
+/** For tests: forget which missing plugins were already logged. */
+export declare function resetHeadlessPluginWarnings(): void;
+/** The worker profile: explicit, else RUFLO_HEADLESS_PLUGINS, else ruflo-mods. */
+export declare function workerProfile(env?: NodeJS.ProcessEnv, explicit?: readonly string[]): string[];
+/** Every `--plugin-dir` value already in argv (both `--plugin-dir x` and `--plugin-dir=x`). */
+export declare function existingPluginDirs(argv: readonly string[]): string[];
+export declare function withHeadlessPlugins<E extends Record<string, string | undefined>>(argv: readonly string[], env: E, opts?: HeadlessPluginOptions): HeadlessPluginResult<E>;
+//# sourceMappingURL=headless-plugins.d.ts.map