@claude-flow/cli 3.51.1 → 3.52.0

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.42.0
+3.51.1

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.51.1",
+    "version": "3.52.0",
     "files": {
       "auto-memory-hook.mjs": "c8d218526a3c34034c2a69de23f507f0eb0f70d59c16426a8edc849e6ac22529",
       "hook-handler.cjs": "fbd827dfac52e48ea1a576a4484826b6570c0fa710ca4c28faad63b003ac1274",
@@ -9,6 +9,6 @@
       "router.cjs": "16648b3c0d73b6681ac2d8d13def6a68286c57f5a11004de5b19a0fa088c833d"
     }
   },
-  "signature": "D+NMHUsWriB+ZO/yQdOlrw4daC5sNvZxsDDxF7Y82SruJc7xd4icePgaDDntBVOq/znDpFZUCqqiUYX7sy0uCw==",
+  "signature": "1Cbum5dGDkHM/a2vsLktQc8gPTFT3CVXUNsq4ReHQLIduwvX8dxpT3nyO1ExAf5lYGPY5fznJlPcRsoh321yDA==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -50,9 +50,26 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov
 
 ---
 
-![The ruflo console inside Claude Code: swarm topology, claims, approvals, missions, events and more](docs/assets/ruflo-console-tour.gif)
+<p align="center"><img src="docs/assets/ruflo-console-walkthrough.gif" alt="A walkthrough of the ruflo console inside Claude Code in a near-square frame: the whole boot (the neon sign in its border, the ruvector constellation, every area checked), the main menu entering and its cards folding, then twenty-odd pages one after another (Swarm, Federation, Sandbox, Cost, Memory, Dev Tools and more), the command palette, ruHelp, settings and refresh"></p>
 
-<sub>The <code>/ruflo</code> console running in Claude Code — <code>npx ruflo init</code>, restart Claude Code, then <code>/ruflo</code>.</sub>
+<sub>The <code>/ruflo</code> console running in Claude Code, shown in a compact, near-square frame (the cockpit docked beside Claude, cropped to the cockpit) so it reads on a phone as well as a desktop: the whole boot (the neon sign in its border, the ruvector constellation lit by what is really installed, every area checked, an easter egg), the main menu entering and its cards folding, the grouped nav, a quick tour of twenty-odd pages (the Swarm topology, the Federation map, the Sandbox page for tmux, RVF and RVM, Cost, Memory, Dev Tools and more), the command palette (a tag on every entry for what it does), <b>ruHelp</b> (built-in help: ask a question, get steps with buttons; a guide for every capability), settings and refresh. A <a href="docs/assets/ruflo-console-walkthrough-wide.gif">wide-display walkthrough</a> shows the same console with room for every label. <code>npx ruflo init</code>, restart Claude Code, then <code>/ruflo</code>.</sub>
+
+**Let Claude drive the console.** The console can also be driven *by* Claude: with control turned on (Settings → Claude control), Claude gets four tools (`console_state`, `console_open`, `console_set`, `console_run`) and sets up a mission, opens the Learning Lab or Security page, or runs a palette entry, while the cockpit shows it happening. How far it may go is your setting (`read`, `write`, `manage`, `full`: an action above the level is refused and nothing runs) and whether it waits for your Yes (`ask`) or confirms itself (`auto`). Overview shows a live log of every action and a **Take back control** button that stops all of it at once. It is off by default. See [ADR-444](v3/docs/adr/ADR-444-claude-controls-the-console.md).
+
+<p align="center"><img src="docs/assets/ruflo-console-claude-control.gif" alt="Claude Code with the ruflo console beside it: Claude sets a mission goal, creates the mission and opens the Learning, Security and Overview pages through the console tools; the Claude control dashboard logs each action; swarm-stop is refused because it needs the full level; the person clicks Take back control and the next request is refused"></p>
+
+<sub>A real recording (Claude Haiku, a few cents): control set to <code>write</code> with auto-confirm. Setting a goal and creating the mission is within that level; stopping a swarm needs <code>full</code>, so it is refused; after <b>Take back control</b> every call is refused.</sub>
+
+**Install the mods from the ruflo marketplace** (Claude Code 2.1.287 or later; mods run with your account's permissions and are not sandboxed, so read the code first):
+
+```text
+/plugin marketplace add ruvnet/ruflo
+/plugin install ruflo-console@ruflo
+/plugin install ruflo-mods@ruflo
+/reload-plugins
+```
+
+`ruflo-console` is the cockpit above, `ruflo-mods` routes prompts and enforces policy in-process, `ruflo-swarm` shows the swarm in a pane, and `ruflo-ruos` adds the ruOS status segment. Open `/plugin` to confirm they appear in the active mods line. Inside the console, `/ruflo market` is the Plugin Catalog: every ruflo plugin, mod and skill with what it ships, and buttons to install, enable, disable and update (each asks first).
 
 ## Quick Start
 

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-10-02T16:06:24.442Z",
-  "gitSha": "09a1cb02",
+  "generatedAt": "2026-10-05T14:24:23.258Z",
+  "gitSha": "0f327015",
   "catalog": {
     "agents": 176,
     "tools": 423,

package/dist/src/commands/guidance.js

@@ -12,6 +12,8 @@ const compileCommand = {
         { name: 'root', short: 'r', type: 'string', description: 'Root guidance file path', default: './CLAUDE.md' },
         { name: 'local', short: 'l', type: 'string', description: 'Local guidance overlay file path' },
         { name: 'output', short: 'o', type: 'string', description: 'Output directory for compiled bundle' },
+        { name: 'mod-projection', type: 'boolean', description: 'Export bounded advisory guidance for the native mod', default: 'false' },
+        { name: 'revision', type: 'string', description: 'Immutable source commit SHA for the mod projection' },
         { name: 'json', type: 'boolean', description: 'Output as JSON', default: 'false' },
     ],
     examples: [
@@ -32,14 +34,29 @@ const compileCommand = {
                 output.writeln(output.error(`Root guidance file not found: ${rootPath}`));
                 return { success: false, message: `File not found: ${rootPath}` };
             }
-            const rootContent = await readFile(rootPath, 'utf-8');
+            const modExport = ctx.flags['mod-projection'] === true;
+            const checked = modExport ? await (await import('../guidance/mod-sources.js')).readModGuidanceSources({
+                rootPath, localPath, revision: String(ctx.flags.revision || ''),
+            }) : undefined;
+            const rootContent = checked ? checked.rootContent : await readFile(rootPath, 'utf-8');
             let localContent;
-            if (localPath && existsSync(localPath)) {
+            if (checked)
+                localContent = checked.localContent;
+            else if (localPath && existsSync(localPath)) {
                 localContent = await readFile(localPath, 'utf-8');
             }
             const { GuidanceCompiler } = await import('@claude-flow/guidance/compiler');
             const compiler = new GuidanceCompiler();
             const bundle = compiler.compile(rootContent, localContent);
+            if (checked) {
+                const { buildModProjection, writeModProjection, MOD_GUIDANCE_DIR } = await import('../guidance/mod-projection.js');
+                const sourceDigests = Object.fromEntries(Object.entries(checked.sources).map(([key, binding]) => [key, binding.sha256]));
+                const projection = buildModProjection(bundle, checked.sourceRevision, sourceDigests);
+                const path = await writeModProjection(String(ctx.flags.output || MOD_GUIDANCE_DIR), projection);
+                const data = { path, projection, sources: checked.sources };
+                output.writeln(jsonOutput ? JSON.stringify(data) : output.success(`Git source matched; advisory mod projection exported: ${path}`));
+                return { success: true, data };
+            }
             if (jsonOutput) {
                 output.writeln(JSON.stringify(bundle, null, 2));
             }
@@ -513,6 +530,28 @@ const abTestCommand = {
         }
     },
 };
+const modCandidatesCommand = {
+    name: 'mod-candidates',
+    description: 'Review unverified native mod observations without training or promotion',
+    options: [
+        { name: 'directory', type: 'string', description: 'Observation directory', default: '.claude-flow/mods/guidance/observations' },
+        { name: 'bundle-id', type: 'string', description: 'Filter to one exported guidance bundle digest' },
+        { name: 'json', type: 'boolean', description: 'Output candidate report as JSON', default: 'false' },
+    ],
+    action: async (ctx) => {
+        try {
+            const { collectModCandidates } = await import('../guidance/mod-projection.js');
+            const data = await collectModCandidates(String(ctx.flags.directory || '.claude-flow/mods/guidance/observations'), ctx.flags['bundle-id']);
+            output.writeln(JSON.stringify(data, null, ctx.flags.json === true ? undefined : 2));
+            return { success: true, data };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            output.writeln(output.error(message));
+            return { success: false, message };
+        }
+    },
+};
 // Main guidance command
 export const guidanceCommand = {
     name: 'guidance',
@@ -520,6 +559,7 @@ export const guidanceCommand = {
     aliases: ['guide', 'policy'],
     subcommands: [
         compileCommand,
+        modCandidatesCommand,
         retrieveCommand,
         gatesCommand,
         statusCommand,
@@ -542,6 +582,7 @@ export const guidanceCommand = {
         output.writeln();
         output.writeln('Available subcommands:');
         output.writeln(`  ${output.bold('compile')}   Compile CLAUDE.md into policy bundle`);
+        output.writeln(`  ${output.bold('mod-candidates')} Review unverified mod observations`);
         output.writeln(`  ${output.bold('retrieve')}  Retrieve task-relevant guidance shards`);
         output.writeln(`  ${output.bold('gates')}     Evaluate enforcement gates`);
         output.writeln(`  ${output.bold('status')}    Show control plane status`);

package/dist/src/guidance/mod-projection.d.ts

@@ -0,0 +1,120 @@
+interface Rule {
+    id: string;
+    text: string;
+    source: string;
+    isConstitution: boolean;
+    intents: string[];
+    priority: number;
+}
+interface Bundle {
+    constitution: {
+        rules: Rule[];
+        hash: string;
+    };
+    shards: {
+        rule: Rule;
+    }[];
+    manifest: {
+        sourceHashes: Record<string, string>;
+    };
+}
+export declare const MOD_GUIDANCE_DIR = ".claude-flow/mods/guidance";
+export interface ModObservation {
+    version: 1;
+    kind: 'guidance-observation';
+    id: string;
+    runId: string;
+    taskId: number;
+    bundleId: string;
+    sourceRevision: string;
+    ruleIds: string[];
+    checks: {
+        allow: number;
+        ask: number;
+        deny: number;
+    };
+    tools: {
+        ok: number;
+        error: number;
+        denied: number;
+    };
+    completion: 'completed' | 'aborted' | 'interrupted';
+    verified: false;
+    learningEligible: false;
+}
+/** Stable digest of the exported rules; a provenance identifier, not a signature. */
+export declare function buildModProjection(bundle: Bundle, sourceRevision: string, sourceDigests?: Record<string, string>): {
+    bundleId: string;
+    entries: {
+        id: string;
+        text: string;
+        source: string;
+        constitution: boolean;
+        intents: string[];
+        priority: number;
+    }[];
+    sourceDigests?: {
+        [k: string]: string;
+    } | undefined;
+    version: 1;
+    sourceRevision: string;
+    constitutionHash: string;
+    sourceHashes: {
+        [k: string]: string;
+    };
+};
+/** Explicit CLI export only. Never called from the native prompt/tool hooks. */
+export declare function writeModProjection(directory: string, projection: ReturnType<typeof buildModProjection>): Promise<string>;
+/** Strict allowlist: a writable `verified: true` or receipt cannot become evidence. */
+export declare function parseModObservations(text: string): ModObservation[];
+/** Review priorities only. Never feeds the accepted RunEvent ledger or optimizer. */
+export declare function collectModCandidates(directory: string, bundleId?: string): Promise<{
+    version: number;
+    status: string;
+    verified: boolean;
+    learningEligible: boolean;
+    observations: number;
+    excluded: number;
+    summary: {
+        files: number;
+        withGuidance: number;
+        withoutGuidance: number;
+        completed: number;
+        aborted: number;
+        interrupted: number;
+        checks: {
+            allow: number;
+            ask: number;
+            deny: number;
+        };
+        tools: {
+            ok: number;
+            error: number;
+            denied: number;
+        };
+    };
+    candidates: {
+        verified: boolean;
+        learningEligible: boolean;
+        toolErrorRate: number | null;
+        deniedCheckRate: number | null;
+        reviewReasons: string[];
+        bundleId: string;
+        sourceRevision: string;
+        ruleId: string;
+        observations: number;
+        affectedObservations: number;
+        toolErrors: number;
+        toolExecutions: number;
+        deniedTools: number;
+        deniedChecks: number;
+        permissionChecks: number;
+        aborted: number;
+        interrupted: number;
+        completed: number;
+    }[];
+    interpretation: string;
+    requiredBeforeLearning: string[];
+}>;
+export {};
+//# sourceMappingURL=mod-projection.d.ts.map

package/dist/src/guidance/mod-projection.js

@@ -0,0 +1,155 @@
+/** Native mod adapter: compiler projection and untrusted review candidates. */
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const MOD_GUIDANCE_DIR = '.claude-flow/mods/guidance';
+const MAX_BYTES = 256 * 1024;
+const HEX = /^[a-f0-9]{64}$/;
+const RUN = /^mod-[a-z0-9]+-[a-z0-9]{1,12}-[a-z0-9]{1,12}$/;
+const ID = /^[A-Z]{1,58}-?\d{3,4}$/;
+/** Stable digest of the exported rules; a provenance identifier, not a signature. */
+export function buildModProjection(bundle, sourceRevision, sourceDigests) {
+    if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sourceRevision))
+        throw new Error('--revision must be an immutable source commit SHA');
+    const rules = [...bundle.constitution.rules, ...bundle.shards.map(s => s.rule)];
+    if (rules.length > 256)
+        throw new Error('Mod projection supports at most 256 rules; supply a reviewed scoped source');
+    const ids = new Set();
+    const entries = rules.map(rule => {
+        if (!ID.test(rule.id) || ids.has(rule.id) || !['root', 'local'].includes(rule.source) || rule.text.length > 1200 ||
+            !Number.isFinite(rule.priority) || rule.priority < 0 || rule.priority > 10000)
+            throw new Error('Unsupported mod guidance rule');
+        ids.add(rule.id);
+        return { id: rule.id, text: rule.text, source: rule.source, constitution: rule.isConstitution, intents: [...rule.intents], priority: rule.priority };
+    }).sort((a, b) => a.id.localeCompare(b.id));
+    const sourceHashes = Object.fromEntries(Object.entries(bundle.manifest.sourceHashes).sort(([a], [b]) => a.localeCompare(b)));
+    if (!/^[a-f0-9]{16}$/.test(bundle.constitution.hash) || Object.entries(sourceHashes).some(([key, value]) => !['root', 'local'].includes(key) || !/^[a-f0-9]{16}$/.test(value))) {
+        throw new Error('Unsupported compiler source hashes');
+    }
+    // The compiler omits an empty local overlay from its manifest. Bind that
+    // explicitly supplied empty source too, without changing compiler semantics.
+    const emptyDigest = createHash('sha256').update('').digest('hex');
+    if (sourceDigests && (Object.entries(sourceHashes).some(([key, hash]) => sourceDigests[key]?.slice(0, 16) !== hash) ||
+        Object.entries(sourceDigests).some(([key, digest]) => !['root', 'local'].includes(key) || !HEX.test(digest) ||
+            (!sourceHashes[key] && !(key === 'local' && digest === emptyDigest)))))
+        throw new Error('Source digests do not match compiler snapshots');
+    const data = { version: 1, sourceRevision, constitutionHash: bundle.constitution.hash, sourceHashes,
+        ...(sourceDigests ? { sourceDigests: Object.fromEntries(Object.entries(sourceDigests).sort(([a], [b]) => a.localeCompare(b))) } : {}), entries };
+    const bundleId = createHash('sha256').update(JSON.stringify(data)).digest('hex');
+    const projection = { ...data, bundleId };
+    if (Buffer.byteLength(JSON.stringify(projection)) > MAX_BYTES)
+        throw new Error('Mod projection exceeds 256 KiB');
+    return projection;
+}
+/** Explicit CLI export only. Never called from the native prompt/tool hooks. */
+export async function writeModProjection(directory, projection) {
+    const serialized = `${JSON.stringify(projection)}\n`;
+    if (Buffer.byteLength(serialized) > MAX_BYTES)
+        throw new Error('Serialized mod projection exceeds 256 KiB');
+    await mkdir(directory, { recursive: true });
+    const target = join(directory, 'projection.json');
+    const temp = join(directory, `.projection-${process.pid}-${Date.now()}.tmp`);
+    await writeFile(temp, serialized, { flag: 'wx', mode: 0o600 });
+    await rename(temp, target);
+    return target;
+}
+const keys = ['version', 'kind', 'id', 'runId', 'taskId', 'bundleId', 'sourceRevision', 'ruleIds', 'checks', 'tools', 'completion', 'verified', 'learningEligible'];
+const counters = (value, names) => value && !Array.isArray(value) && Object.keys(value).length === names.length && names.every(k => Number.isSafeInteger(value[k]) && value[k] >= 0 && value[k] <= 100000);
+/** Strict allowlist: a writable `verified: true` or receipt cannot become evidence. */
+export function parseModObservations(text) {
+    if (Buffer.byteLength(text) > MAX_BYTES)
+        throw new Error('Observation file exceeds 256 KiB');
+    const records = JSON.parse(text);
+    if (!Array.isArray(records) || records.length > 128)
+        throw new Error('Invalid observation queue');
+    const seen = new Set();
+    for (const r of records) {
+        if (!r || Object.keys(r).length !== keys.length || Object.keys(r).some(k => !keys.includes(k)) ||
+            r.version !== 1 || r.kind !== 'guidance-observation' || !RUN.test(r.runId ?? '') ||
+            !Number.isSafeInteger(r.taskId) || r.taskId < 1 || r.id !== `${r.runId}:${r.taskId}` || seen.has(r.id) ||
+            !HEX.test(r.bundleId ?? '') || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(r.sourceRevision ?? '') ||
+            !Array.isArray(r.ruleIds) || r.ruleIds.length > 5 || r.ruleIds.some((id) => typeof id !== 'string' || !ID.test(id)) || new Set(r.ruleIds).size !== r.ruleIds.length ||
+            !counters(r.checks, ['allow', 'ask', 'deny']) || !counters(r.tools, ['ok', 'error', 'denied']) ||
+            !['completed', 'aborted', 'interrupted'].includes(r.completion) || r.verified !== false || r.learningEligible !== false) {
+            throw new Error('Invalid or forged mod observation');
+        }
+        seen.add(r.id);
+    }
+    return records;
+}
+/** Review priorities only. Never feeds the accepted RunEvent ledger or optimizer. */
+export async function collectModCandidates(directory, bundleId) {
+    if (bundleId !== undefined && !HEX.test(bundleId))
+        throw new Error('Invalid bundle ID filter');
+    let names;
+    try {
+        names = (await readdir(directory)).filter(name => /^mod-[a-z0-9-]+\.json$/.test(name)).sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            names = [];
+        else
+            throw error;
+    }
+    if (names.length > 128)
+        throw new Error('At most 128 observation files may be reviewed per batch');
+    const seen = new Set();
+    const groups = new Map();
+    let observations = 0;
+    let excluded = 0;
+    const summary = { files: names.length, withGuidance: 0, withoutGuidance: 0, completed: 0, aborted: 0, interrupted: 0,
+        checks: { allow: 0, ask: 0, deny: 0 }, tools: { ok: 0, error: 0, denied: 0 } };
+    for (const name of names) {
+        const path = join(directory, name);
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_BYTES)
+            throw new Error('Unsafe observation file');
+        for (const r of parseModObservations(await readFile(path, 'utf8'))) {
+            if (name !== `${r.runId}.json`)
+                throw new Error('Observation namespace mismatch');
+            if (seen.has(r.id))
+                throw new Error('Replayed observation');
+            seen.add(r.id);
+            if (bundleId && r.bundleId !== bundleId) {
+                excluded++;
+                continue;
+            }
+            observations++;
+            summary[r.ruleIds.length ? 'withGuidance' : 'withoutGuidance']++;
+            summary[r.completion]++;
+            for (const key of ['allow', 'ask', 'deny'])
+                summary.checks[key] += r.checks[key];
+            for (const key of ['ok', 'error', 'denied'])
+                summary.tools[key] += r.tools[key];
+            for (const ruleId of r.ruleIds) {
+                const key = `${r.bundleId}:${r.sourceRevision}:${ruleId}`;
+                const group = groups.get(key) ?? { bundleId: r.bundleId, sourceRevision: r.sourceRevision, ruleId, observations: 0, affectedObservations: 0,
+                    toolErrors: 0, toolExecutions: 0, deniedTools: 0, deniedChecks: 0, permissionChecks: 0, aborted: 0, interrupted: 0, completed: 0 };
+                group.observations++;
+                group.affectedObservations += r.tools.error > 0 || r.tools.denied > 0 || r.checks.deny > 0 || r.completion !== 'completed' ? 1 : 0;
+                group.toolErrors += r.tools.error;
+                group.toolExecutions += r.tools.ok + r.tools.error;
+                group.deniedTools += r.tools.denied;
+                group.deniedChecks += r.checks.deny;
+                group.permissionChecks += r.checks.allow + r.checks.ask + r.checks.deny;
+                group[r.completion]++;
+                groups.set(key, group);
+            }
+        }
+    }
+    return {
+        version: 1, status: 'pending-independent-verification', verified: false, learningEligible: false,
+        observations, excluded, summary,
+        candidates: [...groups.values()].sort((a, b) => b.affectedObservations - a.affectedObservations || b.toolErrors - a.toolErrors ||
+            b.deniedChecks - a.deniedChecks || a.bundleId.localeCompare(b.bundleId) || a.sourceRevision.localeCompare(b.sourceRevision) || a.ruleId.localeCompare(b.ruleId))
+            .map(group => ({ ...group, verified: false, learningEligible: false,
+            toolErrorRate: group.toolExecutions ? group.toolErrors / group.toolExecutions : null,
+            deniedCheckRate: group.permissionChecks ? group.deniedChecks / group.permissionChecks : null,
+            reviewReasons: [group.toolErrors ? 'observed tool errors' : '', group.deniedTools ? 'denied tool calls' : '', group.deniedChecks ? 'denied checks' : '',
+                group.aborted ? 'aborted turns' : '', group.interrupted ? 'interrupted turns' : ''].filter(Boolean),
+        })),
+        interpretation: 'Activity correlations only. Completed turns are not accepted successes; displayed rules are not proven causes.',
+        requiredBeforeLearning: ['task-bound acceptance evidence', 'held-out baseline and candidate evaluation', 'authorized promotion'],
+    };
+}
+//# sourceMappingURL=mod-projection.js.map

package/dist/src/guidance/mod-sources.d.ts

@@ -0,0 +1,22 @@
+export declare const MAX_GUIDANCE_SOURCE_BYTES: number;
+export interface ModSourceBinding {
+    path: string;
+    blobId: string;
+    sha256: string;
+    byteLength: number;
+}
+/** A commit label alone is insufficient. Both supplied files must match its blobs. */
+export declare function readModGuidanceSources(input: {
+    rootPath: string;
+    localPath?: string;
+    revision: string;
+}): Promise<{
+    sourceRevision: string;
+    rootContent: string;
+    localContent: string | undefined;
+    sources: {
+        local?: ModSourceBinding | undefined;
+        root: ModSourceBinding;
+    };
+}>;
+//# sourceMappingURL=mod-sources.d.ts.map

package/dist/src/guidance/mod-sources.js

@@ -0,0 +1,123 @@
+/** Explicit export only: bind the compiled snapshots to immutable Git blobs. */
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { devNull } from 'node:os';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { promisify } from 'node:util';
+import { safeGitArgv } from '@claude-flow/security/safe-git';
+const run = promisify(execFile);
+const OID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+export const MAX_GUIDANCE_SOURCE_BYTES = 1024 * 1024;
+/** Local reads only; no shell, Git hooks, filters, replacement refs or lazy fetch. */
+async function git(repo, args) {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: devNull, GIT_NO_LAZY_FETCH: '1', GIT_ALLOW_PROTOCOL: '', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' });
+    const { stdout } = await run('git', safeGitArgv(repo, ['--no-replace-objects', '--literal-pathspecs', '-c', `core.hooksPath=${devNull}`, '-c', 'protocol.allow=never', ...args]), {
+        encoding: 'buffer', env, maxBuffer: 2 * MAX_GUIDANCE_SOURCE_BYTES, timeout: 10_000, windowsHide: true,
+    });
+    return stdout;
+}
+/** Older Git ignores GIT_NO_LAZY_FETCH. Refuse all promisor configuration
+ * before reading objects, including repositories whose objects happen to exist.
+ * Shallow clones with ordinary local objects remain supported. */
+async function requireLocalObjects(repo) {
+    try {
+        await git(repo, ['config', '--get-regexp', '^(extensions\\.partialclone|remote\\..*\\.(promisor|partialclonefilter))$']);
+    }
+    catch (error) {
+        const result = error;
+        // git config returns 1 only for no matching entries. Other errors fail closed.
+        if (result.code === 1 && !result.signal && result.stdout?.length === 0 && result.stderr?.length === 0)
+            return;
+        throw error;
+    }
+    throw new Error('Offline mod export does not support partial clones or promisor repositories; use a checkout with local objects');
+}
+async function sourcePath(path) {
+    const absolute = resolve(path);
+    if (/[\u0000-\u001f\u007f]/.test(absolute))
+        throw new Error('Unsupported guidance source path');
+    const stat = await lstat(absolute);
+    if (!stat.isFile() || stat.isSymbolicLink() || await realpath(absolute) !== absolute)
+        throw new Error('Guidance source must be a regular file without symlink components');
+    return absolute;
+}
+/** Descriptor based bounded read; never reread mutable bytes after verification. */
+async function sourceBytes(path) {
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > MAX_GUIDANCE_SOURCE_BYTES)
+            throw new Error('Guidance source exceeds 1 MiB or is not a regular file');
+        const bytes = Buffer.alloc(MAX_GUIDANCE_SOURCE_BYTES + 1);
+        let size = 0;
+        while (size < bytes.length) {
+            const { bytesRead } = await file.read(bytes, size, bytes.length - size, null);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+        }
+        if (size > MAX_GUIDANCE_SOURCE_BYTES)
+            throw new Error('Guidance source exceeds 1 MiB');
+        return bytes.subarray(0, size);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** A commit label alone is insufficient. Both supplied files must match its blobs. */
+export async function readModGuidanceSources(input) {
+    if (!OID.test(input.revision))
+        throw new Error('--revision must be a full immutable source commit SHA');
+    const rootPath = await sourcePath(input.rootPath);
+    let repo;
+    try {
+        repo = (await git(dirname(rootPath), ['rev-parse', '--show-toplevel'])).toString('utf8').replace(/\r?\n$/, '');
+        repo = await realpath(repo);
+    }
+    catch {
+        throw new Error('Guidance source requires a local Git repository');
+    }
+    await requireLocalObjects(repo);
+    try {
+        if ((await git(repo, ['cat-file', '-t', input.revision])).toString('utf8').trim() !== 'commit')
+            throw new Error('not a commit');
+        if ((await git(repo, ['rev-parse', '--verify', `${input.revision}^{commit}`])).toString('utf8').trim() !== input.revision)
+            throw new Error('abbreviated commit');
+    }
+    catch {
+        throw new Error('Guidance source requires an existing full immutable commit');
+    }
+    const read = async (path) => {
+        const absolute = await sourcePath(path);
+        const rel = relative(repo, absolute);
+        if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))
+            throw new Error('Guidance sources must belong to the same Git repository');
+        const sourceRepo = (await git(dirname(absolute), ['rev-parse', '--show-toplevel'])).toString('utf8').replace(/\r?\n$/, '');
+        if (await realpath(sourceRepo) !== repo)
+            throw new Error('Guidance sources must belong to the same Git repository');
+        await requireLocalObjects(repo);
+        const gitPath = rel.split(sep).join('/');
+        const tree = (await git(repo, ['ls-tree', '-z', '--full-tree', input.revision, '--', gitPath])).toString('utf8');
+        const match = /^(100644|100755) blob ([a-f0-9]{40}|[a-f0-9]{64})\t([^\0]+)\0$/.exec(tree);
+        if (!match || match[3] !== gitPath)
+            throw new Error('Guidance source must be a regular tracked blob in the supplied commit');
+        const blobId = match[2];
+        const blobSize = Number((await git(repo, ['cat-file', '-s', blobId])).toString('utf8').trim());
+        if (!Number.isSafeInteger(blobSize) || blobSize < 0 || blobSize > MAX_GUIDANCE_SOURCE_BYTES)
+            throw new Error('Committed guidance source exceeds 1 MiB');
+        const committed = await git(repo, ['cat-file', 'blob', blobId]);
+        const bytes = await sourceBytes(absolute);
+        if (!bytes.equals(committed))
+            throw new Error('Guidance source bytes differ from the supplied commit; commit the reviewed source before exporting');
+        // Preserve a BOM in the compiler snapshot; reject invalid UTF-8 rather than replacing bytes.
+        const content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+        return { content, binding: { path: gitPath, blobId, sha256: createHash('sha256').update(bytes).digest('hex'), byteLength: bytes.length } };
+    };
+    const root = await read(rootPath);
+    const local = input.localPath === undefined ? undefined : await read(input.localPath);
+    return { sourceRevision: input.revision, rootContent: root.content, localContent: local?.content, sources: { root: root.binding, ...(local ? { local: local.binding } : {}) } };
+}
+//# sourceMappingURL=mod-sources.js.map