clef-mcp 0.3.1 → 0.4.0

package/dist/cli.js

@@ -104,9 +104,9 @@ __export(setup_exports, {
 });
 import { execFile as execFile5 } from "child_process";
 import fsSync4 from "fs";
-import fsp10 from "fs/promises";
-import os4 from "os";
-import path11 from "path";
+import fsp13 from "fs/promises";
+import os5 from "os";
+import path12 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function bundledSkillPath() {
   return fileURLToPath2(new URL("../skills/clef-decisions/SKILL.md", import.meta.url));
@@ -114,7 +114,7 @@ function bundledSkillPath() {
 async function mergeJsonServerEntry(file, serverKey, container) {
   let doc = {};
   try {
-    doc = JSON.parse(await fsp10.readFile(file, "utf8"));
+    doc = JSON.parse(await fsp13.readFile(file, "utf8"));
   } catch {
     doc = {};
   }
@@ -131,15 +131,15 @@ async function mergeJsonServerEntry(file, serverKey, container) {
     servers[serverKey] = { command: SERVER_ENTRY.command, args: [...SERVER_ENTRY.args] };
     doc.mcpServers = servers;
   }
-  await fsp10.mkdir(path11.dirname(file), { recursive: true });
-  await fsp10.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
+  await fsp13.mkdir(path12.dirname(file), { recursive: true });
+  await fsp13.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
   return "configured";
 }
 async function setupCodex() {
-  const file = path11.join(HOME(), ".codex", "config.toml");
+  const file = path12.join(HOME(), ".codex", "config.toml");
   let content = "";
   try {
-    content = await fsp10.readFile(file, "utf8");
+    content = await fsp13.readFile(file, "utf8");
   } catch {
     content = "";
   }
@@ -147,24 +147,24 @@ async function setupCodex() {
     return { client: "codex", status: "already-configured", detail: file };
   }
   const next = (content && !content.endsWith("\n") ? content + "\n" : content) + "\n" + CODEX_SECTION;
-  await fsp10.mkdir(path11.dirname(file), { recursive: true });
-  await fsp10.writeFile(file, next, "utf8");
+  await fsp13.mkdir(path12.dirname(file), { recursive: true });
+  await fsp13.writeFile(file, next, "utf8");
   return { client: "codex", status: "configured", detail: file };
 }
 async function setupZcode() {
-  const file = path11.join(HOME(), ".zcode", "cli", "config.json");
+  const file = path12.join(HOME(), ".zcode", "cli", "config.json");
   const status = await mergeJsonServerEntry(file, "clef-mcp", "mcp.servers");
   return { client: "zcode", status, detail: file };
 }
 async function setupCursor() {
-  const file = path11.join(HOME(), ".cursor", "mcp.json");
+  const file = path12.join(HOME(), ".cursor", "mcp.json");
   const status = await mergeJsonServerEntry(file, "clef-mcp", "mcpServers");
   return { client: "cursor", status, detail: file };
 }
 function whichCli(bin) {
-  const dirs = (process.env.PATH ?? "").split(path11.delimiter).filter(Boolean);
+  const dirs = (process.env.PATH ?? "").split(path12.delimiter).filter(Boolean);
   for (const dir of dirs) {
-    const candidate = path11.join(dir, bin);
+    const candidate = path12.join(dir, bin);
     try {
       fsSync4.accessSync(candidate, fsSync4.constants.X_OK);
       return candidate;
@@ -200,19 +200,19 @@ async function setupClaudeCode() {
 }
 async function installSkill() {
   const src = bundledSkillPath();
-  const destDir = path11.join(HOME(), ".agents", "skills", "clef-decisions");
-  const dest = path11.join(destDir, "SKILL.md");
+  const destDir = path12.join(HOME(), ".agents", "skills", "clef-decisions");
+  const dest = path12.join(destDir, "SKILL.md");
   let content = "";
   try {
-    content = await fsp10.readFile(dest, "utf8");
+    content = await fsp13.readFile(dest, "utf8");
   } catch {
   }
-  const incoming = await fsp10.readFile(src, "utf8");
+  const incoming = await fsp13.readFile(src, "utf8");
   if (content === incoming) {
     return { client: "skill", status: "already-configured", detail: dest };
   }
-  await fsp10.mkdir(destDir, { recursive: true });
-  await fsp10.writeFile(dest, incoming, "utf8");
+  await fsp13.mkdir(destDir, { recursive: true });
+  await fsp13.writeFile(dest, incoming, "utf8");
   return { client: "skill", status: "configured", detail: dest };
 }
 function parseClients(raw) {
@@ -281,7 +281,7 @@ var init_setup = __esm({
     init_errors();
     init_prompt();
     SERVER_ENTRY = { command: "clef-mcp", args: [], type: "stdio" };
-    HOME = () => os4.homedir();
+    HOME = () => os5.homedir();
     CODEX_SECTION = [
       "[mcp_servers.clef-mcp]",
       'command = "clef-mcp"',
@@ -492,6 +492,15 @@ var DEFAULT_LIMITS = {
   maxCriteriaDescChars: 1e3,
   maxQuestionIdChars: 128
 };
+var CLASSIFY_LIMITS = {
+  maxProfileBytes: 1024 * 1024,
+  maxRecordBytes: 1024 * 1024,
+  maxResultBytes: 1024 * 1024,
+  maxExamples: 20,
+  maxFields: 1e3,
+  maxDepth: 64,
+  maxMetadataBytes: 16 * 1024
+};
 function intFromEnv(env, key, fallback) {
   const raw = env[key];
   if (!raw?.trim()) return fallback;
@@ -947,21 +956,21 @@ function whichBin(name, platform) {
   }
   return void 0;
 }
-function managedBinary(clefHome, platform, arch, exists) {
+function managedBinary(clefHome, platform, arch, exists2) {
   const platformDir = llamaRuntimeDir(pathsFor(clefHome).runtimeDir, platform, arch);
   const manifest = readRuntimeManifest(path5.join(platformDir, "runtime-manifest.json"));
-  if (manifest && exists(manifest.binaryPath)) return manifest.binaryPath;
+  if (manifest && exists2(manifest.binaryPath)) return manifest.binaryPath;
   const legacy = path5.join(platformDir, llamaServerName(platform));
-  if (exists(legacy)) return legacy;
+  if (exists2(legacy)) return legacy;
   return void 0;
 }
 function resolveLlamaServerBinary(cfg, deps = {}) {
-  const exists = deps.existsExecutable ?? existsExecutable;
+  const exists2 = deps.existsExecutable ?? existsExecutable;
   const which = deps.which ?? ((name) => whichBin(name, deps.platform ?? process.platform));
   const platform = deps.platform ?? process.platform;
   const arch = deps.arch ?? process.arch;
   if (cfg.llamaBin) {
-    if (!exists(cfg.llamaBin)) {
+    if (!exists2(cfg.llamaBin)) {
       throw new ClefError(
         ClefErrorCode.RUNTIME_NOT_FOUND,
         `CLEF_LLAMA_BIN points to a missing or non-executable file: ${cfg.llamaBin}`
@@ -969,7 +978,7 @@ function resolveLlamaServerBinary(cfg, deps = {}) {
     }
     return { source: "env", path: cfg.llamaBin };
   }
-  const managed = managedBinary(cfg.clefHome, platform, arch, exists);
+  const managed = managedBinary(cfg.clefHome, platform, arch, exists2);
   if (managed) return { source: "managed", path: managed };
   const onPath = which("llama-server");
   if (onPath) return { source: "path", path: onPath };
@@ -2350,18 +2359,603 @@ function validateDoc(config, doc) {
   return parsed;
 }
 
+// src/cli/classify.ts
+init_errors();
+
+// src/classify/input.ts
+init_errors();
+import { createHash as createHash3 } from "crypto";
+import fsp8 from "fs/promises";
+import { Readable } from "stream";
+import { parse } from "csv-parse";
+
+// src/classify/profile.ts
+init_errors();
+import { createHash as createHash2 } from "crypto";
+import fsp7 from "fs/promises";
+import { parseAllDocuments } from "yaml";
+import { z as z3 } from "zod";
+function invalid2(message) {
+  return new ClefError(ClefErrorCode.INVALID_INPUT, message);
+}
+var safeId = z3.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/);
+var threshold = z3.number().finite().min(0).max(1);
+var reserved = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype", "<<"]);
+function validateData(value, depth = 0) {
+  if (depth > CLASSIFY_LIMITS.maxDepth) throw invalid2("Profile nesting exceeds the limit");
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value !== "object" || value instanceof Date || value instanceof Map || value instanceof Set) throw invalid2("Profile must contain JSON-compatible data");
+  for (const [key, child] of Object.entries(value)) {
+    if (reserved.has(key)) throw invalid2(`Reserved profile key "${key}"`);
+    validateData(child, depth + 1);
+  }
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function profileSchema(limits) {
+  return z3.strictObject({
+    schema_version: z3.literal(1),
+    name: safeId.max(64),
+    instructions: z3.string().trim().min(1).max(limits.maxInstructionsChars),
+    labels: z3.record(safeId, z3.string().trim().min(1).max(limits.maxCriteriaDescChars)).refine((v) => Object.keys(v).length >= 2 && Object.keys(v).length <= Math.min(100, limits.maxCriteriaPerQuestion), "Expected 2\u2013100 labels within the configured criteria limit"),
+    model: z3.string().trim().min(1).optional(),
+    input: z3.strictObject({
+      id_field: z3.string().min(1).optional(),
+      fields: z3.array(z3.string().min(1)).min(1).max(CLASSIFY_LIMITS.maxFields).refine((v) => new Set(v).size === v.length, "Selected fields must be unique").optional()
+    }).optional(),
+    policy: z3.strictObject({
+      min_probability: threshold.default(0.8),
+      min_margin: threshold.default(0.15),
+      min_confidence: threshold.optional()
+    }).default({ min_probability: 0.8, min_margin: 0.15 }),
+    examples: z3.array(z3.strictObject({ input: z3.record(z3.string(), z3.unknown()), label: safeId })).max(CLASSIFY_LIMITS.maxExamples).optional()
+  }).superRefine((p, ctx) => {
+    for (const example of p.examples ?? []) {
+      if (!Object.hasOwn(p.labels, example.label)) ctx.addIssue({ code: "custom", message: `Example label "${example.label}" is not configured` });
+    }
+  });
+}
+function parseProfile(text, limits) {
+  if (Buffer.byteLength(text) > CLASSIFY_LIMITS.maxProfileBytes) throw invalid2("Profile exceeds the maximum size in bytes");
+  try {
+    const docs = parseAllDocuments(text, { version: "1.2", schema: "core", uniqueKeys: true, stringKeys: true, strict: true, resolveKnownTags: false, customTags: [], merge: false, logLevel: "silent" });
+    if (docs.length !== 1) throw invalid2("Profile must contain exactly one YAML document");
+    const doc = docs[0];
+    if (doc.errors.length || doc.warnings.length) throw invalid2(`Invalid YAML profile: ${(doc.errors[0] ?? doc.warnings[0]).message}`);
+    const data = doc.toJS({ maxAliasCount: 0 });
+    validateData(data);
+    return profileSchema(limits).parse(JSON.parse(canonicalJson(data)));
+  } catch (err) {
+    if (err instanceof ClefError) throw err;
+    throw invalid2(`Invalid profile: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function loadProfile(file, limits) {
+  const handle = await fsp7.open(file, "r");
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > CLASSIFY_LIMITS.maxProfileBytes) throw invalid2("Profile must be a regular file within the size limit");
+    const chunks = [];
+    let size = 0;
+    const stream = handle.createReadStream({ autoClose: false });
+    for await (const chunk of stream) {
+      size += chunk.length;
+      if (size > CLASSIFY_LIMITS.maxProfileBytes) throw invalid2("Profile exceeds the maximum size in bytes");
+      chunks.push(chunk);
+    }
+    return parseProfile(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)), limits);
+  } finally {
+    await handle.close();
+  }
+}
+function selectRecord(profile, record) {
+  if (profile.input?.id_field) {
+    const id = record[profile.input.id_field];
+    if (!Object.hasOwn(record, profile.input.id_field) || !(typeof id === "string" || typeof id === "number" && Number.isFinite(id))) throw invalid2(`Missing or invalid id field "${profile.input.id_field}"`);
+  }
+  if (!profile.input?.fields) return record;
+  return Object.fromEntries(profile.input.fields.map((field) => {
+    if (!Object.hasOwn(record, field)) throw invalid2(`Missing selected field "${field}"`);
+    return [field, record[field]];
+  }));
+}
+function profileState(profile, record) {
+  return { record, ...profile.examples?.length ? { examples: profile.examples } : {} };
+}
+function profileDigest(profile) {
+  return createHash2("sha256").update(canonicalJson(profile)).digest("hex");
+}
+
+// src/classify/input.ts
+async function* decoded(source) {
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  try {
+    for await (const chunk of source) yield decoder.decode(typeof chunk === "string" ? Buffer.from(chunk) : chunk, { stream: true });
+    const tail = decoder.decode();
+    if (tail) yield tail;
+  } catch (err) {
+    throw invalid2(`Cannot read UTF-8 input: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function* boundedLines(source, maxBytes, discardUnterminated = false) {
+  let pieces = [], size = 0, oversized = false, first = true;
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  const line = (terminated) => {
+    let text = "";
+    if (!oversized && (terminated || !discardUnterminated)) {
+      try {
+        text = decoder.decode(Buffer.concat(pieces, size));
+      } catch {
+        throw invalid2("Cannot read UTF-8 input: invalid encoded record");
+      }
+      if (first) text = text.replace(/^\uFEFF/, "");
+      text = text.replace(/\r$/, "");
+    }
+    first = false;
+    return { text, oversized, terminated, bytes: size + (terminated ? 1 : 0) };
+  };
+  for await (const raw of source) {
+    const chunk = typeof raw === "string" ? Buffer.from(raw) : raw;
+    let start = 0;
+    for (; ; ) {
+      const end = chunk.indexOf(10, start);
+      const part = chunk.subarray(start, end < 0 ? void 0 : end);
+      size += part.length;
+      if (!oversized) {
+        if (size > maxBytes) {
+          oversized = true;
+          pieces = [];
+        } else if (part.length) pieces.push(part);
+      }
+      if (end < 0) break;
+      yield line(true);
+      pieces = [];
+      size = 0;
+      oversized = false;
+      start = end + 1;
+    }
+  }
+  if (size) yield line(false);
+}
+async function* readRows(source, format) {
+  let row = 0;
+  if (format === "jsonl") {
+    for await (const line of boundedLines(source, CLASSIFY_LIMITS.maxRecordBytes)) {
+      if (!line.oversized && !line.text.trim()) continue;
+      row++;
+      try {
+        if (line.oversized) throw invalid2("Record exceeds the maximum size");
+        const record = JSON.parse(line.text);
+        if (record === null || typeof record !== "object" || Array.isArray(record)) throw invalid2("JSONL records must be JSON objects");
+        yield { row, record };
+      } catch (err) {
+        yield { row, error: errorJson(invalid2(`Row ${row}: ${err instanceof Error ? err.message : String(err)}`)).error };
+      }
+    }
+    return;
+  }
+  const parser = parse({
+    bom: true,
+    cast: false,
+    skip_empty_lines: true,
+    relax_column_count: false,
+    max_record_size: CLASSIFY_LIMITS.maxRecordBytes,
+    columns: (headers) => {
+      if (headers.length > CLASSIFY_LIMITS.maxFields || headers.some((h) => !h.trim()) || new Set(headers).size !== headers.length) throw invalid2("CSV headers must be nonempty, unique and within the field limit");
+      if (headers.some((h) => ["__proto__", "constructor", "prototype"].includes(h))) throw invalid2("Reserved CSV header");
+      return headers;
+    }
+  });
+  const upstream = Readable.from(decoded(source));
+  upstream.on("error", (err) => parser.destroy(err));
+  upstream.pipe(parser);
+  try {
+    for await (const record of parser) yield { row: ++row, record };
+  } catch (err) {
+    throw invalid2(`Invalid CSV: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    upstream.destroy();
+    parser.destroy();
+  }
+}
+async function* fileChunks(handle) {
+  let position = 0;
+  for (; ; ) {
+    const buffer = Buffer.alloc(64 * 1024);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+    if (!bytesRead) return;
+    position += bytesRead;
+    yield buffer.subarray(0, bytesRead);
+  }
+}
+function sameFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+async function openInput(file, requestedFormat, _limits) {
+  const format = requestedFormat ?? (file === "-" ? "jsonl" : file.toLowerCase().endsWith(".jsonl") ? "jsonl" : file.toLowerCase().endsWith(".csv") ? "csv" : void 0);
+  if (format !== "jsonl" && format !== "csv") throw invalid2("Use --format jsonl|csv for this input");
+  if (file === "-") return { format, records: () => readRows(process.stdin.iterator({ destroyOnReturn: false }), format), verifyUnchanged: async () => {
+  }, close: async () => {
+  } };
+  const handle = await fsp8.open(file, "r");
+  try {
+    const initial = await handle.stat();
+    if (!initial.isFile()) throw invalid2("Input must be a regular file or stdin");
+    const verifyUnchanged = async () => {
+      let currentPath;
+      try {
+        currentPath = await fsp8.stat(file);
+      } catch {
+        throw invalid2("Input changed during classification");
+      }
+      if (!sameFile(initial, await handle.stat()) || !sameFile(initial, currentPath)) throw invalid2("Input changed during classification");
+    };
+    const hash = createHash3("sha256");
+    for await (const chunk of fileChunks(handle)) hash.update(chunk);
+    await verifyUnchanged();
+    return { format, fingerprint: hash.digest("hex"), records: () => readRows(fileChunks(handle), format), verifyUnchanged, close: () => handle.close() };
+  } catch (err) {
+    await handle.close();
+    throw err;
+  }
+}
+
+// src/classify/output.ts
+init_errors();
+import { randomUUID } from "crypto";
+import { constants } from "fs";
+import fsp9 from "fs/promises";
+import os2 from "os";
+import path8 from "path";
+import { z as z4 } from "zod";
+var baseShape = { row: z4.number().int().positive(), id: z4.string().optional(), profile: z4.string().min(1), model: z4.string().min(1) };
+var policyShape = {
+  label: z4.string().nullable(),
+  suggested_label: z4.string(),
+  probability: z4.number().min(0).max(1),
+  margin: z4.number().min(0).max(1),
+  probabilities: z4.record(z4.string(), z4.number().min(0).max(1)),
+  confidence: z4.number().min(0).max(1).optional(),
+  review_reasons: z4.array(z4.enum(["low_probability", "low_margin", "tie", "low_confidence", "missing_confidence"])),
+  usage: z4.strictObject({ input_tokens: z4.number().optional(), output_tokens: z4.number().optional(), latency_ms: z4.number().optional() }).optional()
+};
+var resultSchema = z4.discriminatedUnion("status", [
+  z4.strictObject({ ...baseShape, ...policyShape, status: z4.literal("classified") }),
+  z4.strictObject({ ...baseShape, ...policyShape, status: z4.literal("needs_review") }),
+  z4.strictObject({ ...baseShape, status: z4.literal("error"), label: z4.null(), error: z4.strictObject({ code: z4.enum(Object.values(ClefErrorCode)), message: z4.string(), hint: z4.string().optional() }) })
+]);
+function validateResult(value, expectedRow, metadata) {
+  const parsed = resultSchema.safeParse(value);
+  if (!parsed.success) throw invalid2("Invalid classification result in checkpoint");
+  const result = parsed.data;
+  if (result.row !== expectedRow || result.profile !== metadata.profile || result.model !== metadata.model) throw invalid2("Checkpoint row sequence or profile/model identity does not match");
+  if (result.status === "error") return;
+  const entries = Object.entries(result.probabilities).sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  if (entries.length < 2 || entries.length > 100 || Math.abs(entries.reduce((s, [, p]) => s + p, 0) - 1) > 1e-3 + 1e-12 || entries[0][0] !== result.suggested_label || Math.abs(entries[0][1] - result.probability) > 1e-12 || Math.abs(entries[0][1] - entries[1][1] - result.margin) > 1e-12 || (result.status === "classified" ? result.label !== result.suggested_label || result.review_reasons.length !== 0 || result.margin === 0 : result.label !== null || result.review_reasons.length === 0)) throw invalid2("Invalid classification policy fields in checkpoint");
+}
+async function exists(file) {
+  try {
+    await fsp9.lstat(file);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+async function protectFiles(candidates, protectedPaths) {
+  for (const candidate of candidates) {
+    for (const source of protectedPaths.filter((p) => p !== "-")) {
+      if (path8.resolve(candidate) === path8.resolve(source)) throw invalid2("Output must not overwrite an input or profile file");
+      try {
+        const [a, b] = await Promise.all([fsp9.stat(candidate), fsp9.stat(source)]);
+        if (a.dev === b.dev && a.ino === b.ino) throw invalid2("Output aliases an input or profile file");
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
+    }
+  }
+}
+async function openRegular(file, write = false) {
+  const handle = await fsp9.open(file, (write ? constants.O_RDWR | constants.O_APPEND : constants.O_RDONLY) | (constants.O_NOFOLLOW ?? 0));
+  const stat = await handle.stat();
+  if (!stat.isFile() || stat.nlink !== 1 || (await fsp9.lstat(file)).isSymbolicLink()) {
+    await handle.close();
+    throw invalid2("Checkpoint and metadata must be regular files without links");
+  }
+  return handle;
+}
+async function readJson(file) {
+  const handle = await openRegular(file);
+  try {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of fileChunks(handle)) {
+      size += chunk.length;
+      if (size > CLASSIFY_LIMITS.maxMetadataBytes) throw invalid2("Checkpoint metadata or lock exceeds the size limit");
+      chunks.push(chunk);
+    }
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+  } finally {
+    await handle.close();
+  }
+}
+async function acquireLock(file, resume) {
+  const lock = `${file}.lock`, claim = `${lock}.claim`, token = randomUUID();
+  let guard;
+  try {
+    guard = await fsp9.open(claim, "wx", 384);
+  } catch {
+    throw invalid2(`Output lock acquisition is busy: ${claim}. Preserve active locks; inspect a crash-left claim before removing it.`);
+  }
+  try {
+    if (await exists(lock)) {
+      const owner = await readJson(lock);
+      let dead = false;
+      if (resume && owner.host === os2.hostname() && Number.isInteger(owner.pid) && owner.pid > 0 && owner.pid <= 2147483647 && typeof owner.token === "string") {
+        try {
+          process.kill(owner.pid, 0);
+        } catch (err) {
+          dead = err.code === "ESRCH";
+        }
+      }
+      if (!dead) throw invalid2(`Output lock belongs to an active or unverifiable writer: ${lock}`);
+      await fsp9.unlink(lock);
+    }
+    const handle = await fsp9.open(lock, "wx", 384);
+    try {
+      await handle.writeFile(JSON.stringify({ pid: process.pid, host: os2.hostname(), token }));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } finally {
+    await guard.close();
+    await fsp9.unlink(claim);
+  }
+  return async () => {
+    const owner = await readJson(lock);
+    if (owner.token === token) await fsp9.unlink(lock);
+  };
+}
+async function writeMetadata(file, metadata) {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  const handle = await fsp9.open(temp, "wx", 384);
+  try {
+    await handle.writeFile(JSON.stringify(metadata) + "\n");
+    await handle.sync();
+    await fsp9.link(temp, file);
+  } finally {
+    await handle.close();
+    await fsp9.unlink(temp);
+  }
+}
+async function openOutput(options) {
+  const { metadata } = options;
+  let handle, release;
+  let completed = 0, closed = false, createdOutput = false;
+  try {
+    if (options.resume && !options.path) throw invalid2("--resume requires --output");
+    if (options.path) {
+      const file = options.path;
+      await protectFiles([file, `${file}.meta.json`, `${file}.lock`, `${file}.lock.claim`], options.protectedPaths ?? []);
+      if (!options.resume && (await exists(file) || await exists(`${file}.meta.json`))) throw invalid2("Output or metadata already exists; use --resume or a new output path");
+      release = await acquireLock(file, !!options.resume);
+      if (options.resume) {
+        if (canonicalJson(await readJson(`${file}.meta.json`)) !== canonicalJson(metadata)) throw invalid2("Resume metadata does not match input, profile, model, runtime or format");
+        handle = await openRegular(file, true);
+        let safeOffset = 0, partial = false;
+        for await (const line of boundedLines(fileChunks(handle), CLASSIFY_LIMITS.maxResultBytes, true)) {
+          if (!line.terminated) {
+            partial = true;
+            break;
+          }
+          if (line.oversized) throw invalid2("Checkpoint result exceeds the size limit");
+          let value;
+          try {
+            value = JSON.parse(line.text);
+          } catch {
+            throw invalid2("Corrupt complete JSONL checkpoint row");
+          }
+          validateResult(value, completed + 1, metadata);
+          completed++;
+          safeOffset += line.bytes;
+        }
+        if (partial) {
+          await handle.truncate(safeOffset);
+          await handle.sync();
+        }
+      } else {
+        handle = await fsp9.open(file, "wx", 384);
+        createdOutput = true;
+        await writeMetadata(`${file}.meta.json`, metadata);
+      }
+    }
+  } catch (err) {
+    try {
+      await handle?.close();
+    } finally {
+      if (createdOutput && options.path) await fsp9.unlink(options.path);
+      await release?.();
+    }
+    throw err;
+  }
+  const stream = options.stream ?? process.stdout;
+  return {
+    get completedRows() {
+      return completed;
+    },
+    async append(result) {
+      if (closed) throw invalid2("Output is closed");
+      validateResult(result, completed + 1, metadata);
+      const line = JSON.stringify(result) + "\n";
+      if (Buffer.byteLength(line) > CLASSIFY_LIMITS.maxResultBytes) throw invalid2("Result exceeds the maximum size");
+      if (handle) {
+        await handle.writeFile(line, "utf8");
+        await handle.sync();
+      } else await new Promise((resolve, reject) => stream.write(line, (err) => err ? reject(err) : resolve()));
+      completed = result.row;
+    },
+    async finish(totalRows) {
+      if (completed !== totalRows) throw invalid2("Checkpoint rows exceed the input or processing is incomplete");
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      try {
+        await handle?.close();
+      } finally {
+        await release?.();
+      }
+    }
+  };
+}
+
+// src/classify/policy.ts
+init_errors();
+function evaluateClassification(profile, decision) {
+  const entries = Object.entries(decision.answer);
+  const labels = Object.keys(profile.labels);
+  const total = entries.reduce((sum, [, p]) => sum + p, 0);
+  if (entries.length !== labels.length || entries.some(([label, p]) => !Object.hasOwn(profile.labels, label) || !Number.isFinite(p) || p < 0 || p > 1) || Math.abs(total - 1) > 1e-3 + 1e-12 || decision.confidence !== void 0 && (!Number.isFinite(decision.confidence) || decision.confidence < 0 || decision.confidence > 1)) {
+    throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, "Runtime returned an invalid classification distribution or confidence");
+  }
+  const ranked = entries.sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const top = ranked[0];
+  const margin = top[1] - ranked[1][1];
+  const reasons = [];
+  if (top[1] < profile.policy.min_probability - 1e-12) reasons.push("low_probability");
+  if (margin < profile.policy.min_margin - 1e-12) reasons.push("low_margin");
+  if (top[1] === ranked[1][1]) reasons.push("tie");
+  if (profile.policy.min_confidence !== void 0) {
+    if (decision.confidence === void 0) reasons.push("missing_confidence");
+    else if (decision.confidence < profile.policy.min_confidence - 1e-12) reasons.push("low_confidence");
+  }
+  return {
+    status: reasons.length ? "needs_review" : "classified",
+    label: reasons.length ? null : top[0],
+    suggested_label: top[0],
+    probability: top[1],
+    margin,
+    probabilities: decision.answer,
+    ...decision.confidence !== void 0 ? { confidence: decision.confidence } : {},
+    review_reasons: reasons
+  };
+}
+
+// src/cli/classify.ts
+async function runClassify(inputPath, options) {
+  const config = loadConfig();
+  const profile = await loadProfile(options.profile, config.limits);
+  const model = options.model ?? profile.model ?? config.model;
+  const spec = getModelSpec(model);
+  if (options.resume && (inputPath === "-" || !options.output)) throw invalid2("--resume requires a regular input file and --output");
+  const loader = new RuntimeLoader(config, createLogger(config.logLevel));
+  let source, output;
+  let interrupted = false, total = 0;
+  const counts = { classified: 0, needs_review: 0, errors: 0, skipped: 0 };
+  const interrupt = () => {
+    interrupted = true;
+    if (inputPath === "-") process.stdin.destroy();
+  };
+  process.on("SIGINT", interrupt);
+  process.on("SIGTERM", interrupt);
+  try {
+    source = await openInput(inputPath, options.format, config.limits);
+    if (interrupted) return 130;
+    output = await openOutput({
+      path: options.output,
+      resume: options.resume,
+      protectedPaths: [inputPath, options.profile],
+      metadata: { schema_version: 1, input_sha256: source.fingerprint ?? "", profile_sha256: profileDigest(profile), profile: profile.name, model, runtime: config.runtime, format: source.format }
+    });
+    await source.verifyUnchanged();
+    const committed = output.completedRows;
+    const commit = async (result) => {
+      await source.verifyUnchanged();
+      await output.append(result);
+    };
+    for await (const row of source.records()) {
+      if (interrupted) break;
+      total = row.row;
+      if (row.row <= committed) {
+        counts.skipped++;
+        continue;
+      }
+      const rawId = profile.input?.id_field && row.record ? row.record[profile.input.id_field] : void 0;
+      const base = { row: row.row, ...typeof rawId === "string" || typeof rawId === "number" && Number.isFinite(rawId) ? { id: String(rawId) } : {}, profile: profile.name, model };
+      let doc;
+      let rowError = row.error;
+      if (!rowError) {
+        try {
+          const selected = selectRecord(profile, row.record);
+          doc = { model, state: profileState(profile, selected), questions: {
+            classification: { type: "choice", instructions: profile.instructions, criteria: profile.labels }
+          } };
+          clefDecideInputSchema(config.limits).parse(doc);
+          validateStateSize(doc.state, config.limits);
+        } catch (err) {
+          rowError = errorJson(err instanceof ClefError ? err : invalid2(err instanceof Error ? err.message : String(err))).error;
+        }
+      }
+      if (rowError) {
+        await commit({ ...base, status: "error", label: null, error: rowError });
+        counts.errors++;
+        continue;
+      }
+      const { runtime } = await loader.ensure(spec);
+      if (interrupted) break;
+      await source.verifyUnchanged();
+      const response = await runtime.decide(toSystemOneRequest(doc, model));
+      const adapted = fromSystemOneResponse(response, doc.questions, model);
+      const result = evaluateClassification(profile, adapted.decisions.classification);
+      await commit({ ...base, ...result, ...adapted.usage ? { usage: adapted.usage } : {} });
+      counts[result.status]++;
+    }
+    if (interrupted) return 130;
+    await source.verifyUnchanged();
+    await output.finish(total);
+    return counts.errors ? 1 : 0;
+  } catch (err) {
+    if (interrupted) return 130;
+    throw err;
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", interrupt);
+    try {
+      await loader.dispose();
+    } finally {
+      try {
+        await output?.close();
+      } finally {
+        try {
+          await source?.close();
+        } finally {
+          process.stderr.write(`classification summary: ${JSON.stringify(counts)}${interrupted ? " (interrupted)" : ""}
+`);
+        }
+      }
+    }
+  }
+}
+
 // src/cli/doctor.ts
 init_errors();
 import { execFile as execFile3 } from "child_process";
-import os3 from "os";
+import os4 from "os";
 import { promisify } from "util";
-import fsp7 from "fs/promises";
-import path8 from "path";
+import fsp10 from "fs/promises";
+import path9 from "path";
 
 // src/models/platform.ts
 init_errors();
 import { execFile as execFile2 } from "child_process";
-import os2 from "os";
+import os3 from "os";
 function exec(cmd, args, timeoutMs) {
   return new Promise((resolve, reject) => {
     execFile2(cmd, args, { timeout: timeoutMs, encoding: "utf8" }, (err, stdout) => {
@@ -2414,7 +3008,7 @@ async function detectPlatform() {
   const info = {
     platform,
     arch: process.arch,
-    totalMemBytes: os2.totalmem()
+    totalMemBytes: os3.totalmem()
   };
   if (platform === "darwin") info.gpu = await gpuInfoDarwin();
   else if (platform === "linux") info.gpu = await gpuInfoLinux();
@@ -2508,16 +3102,16 @@ async function checkBinaryVersion(binaryPath) {
   }
 }
 async function detectMcpConfigs() {
-  const home = os3.homedir();
+  const home = os4.homedir();
   const hints = [
-    { client: "Codex", path: path8.join(home, ".codex", "config.toml"), configured: false },
-    { client: "Claude Code (user)", path: path8.join(home, ".claude.json"), configured: false },
-    { client: "Claude Code (project)", path: path8.resolve(".mcp.json"), configured: false },
-    { client: "Cursor", path: path8.join(process.cwd(), ".cursor", "mcp.json"), configured: false }
+    { client: "Codex", path: path9.join(home, ".codex", "config.toml"), configured: false },
+    { client: "Claude Code (user)", path: path9.join(home, ".claude.json"), configured: false },
+    { client: "Claude Code (project)", path: path9.resolve(".mcp.json"), configured: false },
+    { client: "Cursor", path: path9.join(process.cwd(), ".cursor", "mcp.json"), configured: false }
   ];
   for (const hint of hints) {
     try {
-      const content = await fsp7.readFile(hint.path, "utf8");
+      const content = await fsp10.readFile(hint.path, "utf8");
       hint.configured = content.includes("clef-mcp");
     } catch {
       hint.configured = false;
@@ -2730,14 +3324,14 @@ init_errors();
 // src/models/llama-install.ts
 init_errors();
 import { execFile as execFile4 } from "child_process";
-import fsp9 from "fs/promises";
-import path10 from "path";
+import fsp12 from "fs/promises";
+import path11 from "path";
 
 // src/models/hf.ts
 init_errors();
-import { createHash as createHash2 } from "crypto";
-import fsp8 from "fs/promises";
-import path9 from "path";
+import { createHash as createHash4 } from "crypto";
+import fsp11 from "fs/promises";
+import path10 from "path";
 var HF_BASE_URL = "https://huggingface.co";
 function resolveUrl(repo, revision, file) {
   return `${HF_BASE_URL}/${repo}/resolve/${revision}/${file}`;
@@ -2794,8 +3388,8 @@ async function downloadOnce(url, dest, opts) {
     throw new Error(`HTTP ${res.status}`);
   }
   const total = opts.expectedSize ?? (res.headers.get("content-length") ? Number(res.headers.get("content-length")) : void 0);
-  const hash = createHash2("sha256");
-  const handle = await fsp8.open(dest, "w");
+  const hash = createHash4("sha256");
+  const handle = await fsp11.open(dest, "w");
   let bytes = 0;
   try {
     for await (const chunk of res.body) {
@@ -2810,7 +3404,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const sha256 = hash.digest("hex");
   if (opts.expectedSha256 && sha256 !== opts.expectedSha256) {
-    await fsp8.rm(dest, { force: true });
+    await fsp11.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.CHECKSUM_MISMATCH,
       `Checksum mismatch after download: expected ${opts.expectedSha256}, got ${sha256}`,
@@ -2818,7 +3412,7 @@ async function downloadOnce(url, dest, opts) {
     );
   }
   if (opts.expectedSize !== void 0 && bytes !== opts.expectedSize) {
-    await fsp8.rm(dest, { force: true });
+    await fsp11.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
       `Downloaded size mismatch: expected ${opts.expectedSize} bytes, got ${bytes}`
@@ -2836,17 +3430,17 @@ async function installModel(opts) {
     return { manifest: existing, alreadyInstalled: true };
   }
   const info = await fetchFileInfo(modelSpec.repo, modelSpec.revision, quantSpec.file);
-  const finalPath = path9.join(path9.dirname(manifestPath2), quantSpec.file);
-  await fsp8.mkdir(path9.dirname(finalPath), { recursive: true });
-  const tmpPath = path9.join(path9.dirname(finalPath), `.download-${quantSpec.file}`);
-  await fsp8.rm(tmpPath, { force: true });
+  const finalPath = path10.join(path10.dirname(manifestPath2), quantSpec.file);
+  await fsp11.mkdir(path10.dirname(finalPath), { recursive: true });
+  const tmpPath = path10.join(path10.dirname(finalPath), `.download-${quantSpec.file}`);
+  await fsp11.rm(tmpPath, { force: true });
   opts.log?.info("downloading model", { repo: modelSpec.repo, file: quantSpec.file });
   const result = await downloadFile(info.downloadUrl, tmpPath, {
     expectedSha256: info.sha256,
     expectedSize: info.size ?? quantSpec.bytes,
     onProgress: opts.onProgress
   });
-  await fsp8.rename(tmpPath, finalPath);
+  await fsp11.rename(tmpPath, finalPath);
   const manifest = {
     schemaVersion: 1,
     model: modelSpec.id,
@@ -2934,12 +3528,12 @@ async function findServerBinary(dir, platform) {
     const current = queue.shift();
     let entries;
     try {
-      entries = await fsp9.readdir(current, { withFileTypes: true });
+      entries = await fsp12.readdir(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
-      const full = path10.join(current, entry.name);
+      const full = path11.join(current, entry.name);
       if (entry.isDirectory()) queue.push(full);
       else if (entry.name === target) return full;
     }
@@ -2950,14 +3544,14 @@ async function findServerBinary(dir, platform) {
   );
 }
 async function extractRelease(archivePath, destDir, platform) {
-  await fsp9.mkdir(destDir, { recursive: true });
+  await fsp12.mkdir(destDir, { recursive: true });
   const args = archivePath.endsWith(".zip") ? ["-xf", archivePath] : ["-xzf", archivePath];
   try {
     await execTar(args, destDir);
   } catch (err) {
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
-      `Could not extract ${path10.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
+      `Could not extract ${path11.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
       "Extract the archive manually and point CLEF_LLAMA_BIN at llama-server."
     );
   }
@@ -2967,7 +3561,7 @@ async function ensureLlamaRuntime(cfg, log) {
     const resolved = resolveLlamaServerBinary(cfg);
     if (resolved.source === "managed") {
       const platformDir = llamaRuntimeDir(pathsFor(cfg.clefHome).runtimeDir, process.platform, process.arch);
-      const manifest = readRuntimeManifest(path10.join(platformDir, "runtime-manifest.json"));
+      const manifest = readRuntimeManifest(path11.join(platformDir, "runtime-manifest.json"));
       return { ...resolved, releaseTag: manifest?.releaseTag ?? "unknown", freshInstall: false };
     }
     return { ...resolved, releaseTag: resolved.source, freshInstall: false };
@@ -2999,16 +3593,16 @@ async function downloadManagedLlama(cfg, log) {
   }
   const asset = pickAsset(release, platform, arch);
   log?.info("downloading llama.cpp runtime", { tag: release.tag_name, asset: asset.name });
-  const tagDir = path10.join(platformDir, release.tag_name);
-  await fsp9.mkdir(tagDir, { recursive: true });
-  const tmpArchive = path10.join(platformDir, `.download-${asset.name}`);
-  await fsp9.rm(tmpArchive, { force: true });
+  const tagDir = path11.join(platformDir, release.tag_name);
+  await fsp12.mkdir(tagDir, { recursive: true });
+  const tmpArchive = path11.join(platformDir, `.download-${asset.name}`);
+  await fsp12.rm(tmpArchive, { force: true });
   const result = await downloadFile(asset.browser_download_url, tmpArchive, { expectedSize: asset.size, attempts: 3 });
   await extractRelease(tmpArchive, tagDir, platform);
-  await fsp9.rm(tmpArchive, { force: true });
+  await fsp12.rm(tmpArchive, { force: true });
   const binaryPath = await findServerBinary(tagDir, platform);
-  if (platform !== "win32") await fsp9.chmod(binaryPath, 493);
-  await writeRuntimeManifest(path10.join(platformDir, "runtime-manifest.json"), {
+  if (platform !== "win32") await fsp12.chmod(binaryPath, 493);
+  await writeRuntimeManifest(path11.join(platformDir, "runtime-manifest.json"), {
     schemaVersion: 1,
     kind: "llama-cpp",
     releaseTag: release.tag_name,
@@ -3024,11 +3618,11 @@ async function removeManagedRuntime(cfg) {
   const { runtimeDir } = pathsFor(cfg.clefHome);
   const dir = llamaRuntimeDir(runtimeDir, process.platform, process.arch);
   try {
-    await fsp9.stat(dir);
+    await fsp12.stat(dir);
   } catch {
     return false;
   }
-  await fsp9.rm(dir, { recursive: true, force: true });
+  await fsp12.rm(dir, { recursive: true, force: true });
   return true;
 }
 
@@ -3036,7 +3630,7 @@ async function removeManagedRuntime(cfg) {
 init_prompt();
 
 // src/version.ts
-var VERSION = "0.3.1";
+var VERSION = "0.4.0";
 
 // src/cli/install.ts
 var OS_NAMES = {
@@ -3225,7 +3819,7 @@ async function runStatus() {
 
 // src/cli/uninstall.ts
 init_errors();
-import fsp11 from "fs/promises";
+import fsp14 from "fs/promises";
 init_prompt();
 async function runUninstall(opts) {
   const config = loadConfig();
@@ -3264,7 +3858,7 @@ async function runUninstall(opts) {
     return;
   }
   if (target) {
-    await fsp11.rm(target, { recursive: true, force: true });
+    await fsp14.rm(target, { recursive: true, force: true });
     console.log(`Removed: ${target}`);
   }
   if (opts.runtime) {
@@ -3291,6 +3885,13 @@ program.action(async () => {
     handleCliError(err);
   }
 });
+program.command("classify <input>").description('Classify JSONL/CSV records using a YAML profile; uncertain results require review. Use "-" for stdin.').requiredOption("--profile <path>", "YAML classification profile").option("--output <path>", "JSONL output file (default: stdout; existing files are protected)").option("--format <format>", "input format: jsonl or csv (default: file extension, JSONL for stdin)").option("--model <id>", "override the profile model and CLEF_MODEL").option("--resume", "resume a matching file input/output checkpoint").action(async (input, opts) => {
+  try {
+    process.exit(await runClassify(input, opts));
+  } catch (err) {
+    handleCliError(err);
+  }
+});
 program.command("decide").description("One-shot decision (no MCP session): JSON in, strict JSON result out. For hooks, CI and scripts.").option("--state <source>", 'state: file path, "-" for stdin, or inline JSON/text').option("--questions <source>", 'questions map: file path, "-" for stdin, or inline JSON').option("--model <id>", "model to use (default: CLEF_MODEL or clef-flash)").option("--daemon", "route through a running `clef-mcp daemon` (falls back to a cold run when none is reachable)").action(async (opts) => {
   try {
     await runDecide(opts);