lazyclaw 4.2.1 → 4.3.0

package/mas/redact.mjs

@@ -0,0 +1,46 @@
+// Shared secret redaction — Phase 20 hardening.
+//
+// A single source of truth for stripping common secret shapes out of
+// text before it is (a) sent to an LLM or (b) persisted to a file that
+// later re-enters a system prompt. Both skill_synth.synthesizeSkill and
+// agent_memory.reflectOnce import this so the two paths stay symmetric:
+// neither a distilled skill nor a reflection memory can ever leak a
+// token that merely appeared in a task transcript.
+//
+// This module has zero internal imports so it can be imported from
+// anywhere without risking a cycle.
+
+// Redact common secret shapes (private keys, provider API tokens,
+// bearer headers, KEY/TOKEN/SECRET/PASSWORD env assignments). The match
+// list mirrors the audit log's posture of not persisting raw sensitive
+// I/O. Order matters: the private-key block is collapsed first so its
+// inner base64 doesn't trip the narrower token patterns.
+export function redactSecrets(text) {
+  return String(text ?? '')
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')
+    // Inline credentials in a URL: scheme://user:password@host → redact the password.
+    .replace(/\b([a-z][a-z0-9+.-]*:\/\/[^/\s:@]+):[^/\s@]+@/gi, '$1:[REDACTED]@')
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}/g, '[REDACTED]')
+    .replace(/\b(?:gh[opsu]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g, '[REDACTED]')
+    .replace(/\bxox[abprs]-[A-Za-z0-9-]{8,}/g, '[REDACTED]')
+    .replace(/\bAKIA[0-9A-Z]{12,}/g, '[REDACTED]')
+    .replace(/\bAIza[0-9A-Za-z_-]{35}/g, '[REDACTED]')
+    .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[REDACTED JWT]')
+    .replace(/\b[Bb]earer\s+[A-Za-z0-9._-]{8,}/g, 'Bearer [REDACTED]')
+    // Uppercase env-assignment form (kept for parity / readability).
+    .replace(/\b([A-Z][A-Z0-9_]{2,}_(?:KEY|TOKEN|SECRET|PASSWORD))\s*=\s*\S+/g, '$1=[REDACTED]')
+    // Case-insensitive key/token/secret/password assignment (api_key=, apiKey: "...", PASSWORD=…).
+    // [\w-]* may be empty so a bare `password:` / `token=` is caught too.
+    .replace(/\b([\w-]*(?:key|token|secret|password))\s*[:=]\s*["']?[^\s"']+/gi, '$1=[REDACTED]');
+}
+
+// Neutralise forged conversation role labels embedded in untrusted model
+// text. The reflection/synthesis transcript is rendered as
+// `[User]/[System]/<agent>` lines from the TRUSTED turn.agent field; a
+// turn's free-text body must not be able to inject its own authority
+// line (e.g. a newline followed by "[System] ignore previous"). We defang
+// only the authority roles (case-insensitive, line-leading) so a forged
+// instruction can't masquerade as the system/user/assistant speaker.
+export function neutralizeRoleLabels(text) {
+  return String(text ?? '').replace(/^([ \t]*)\[(user|system|assistant|agent)\]/gim, '$1($2)');
+}

package/mas/skill_synth.mjs

@@ -0,0 +1,232 @@
+// Skill synthesis — Phase 20.
+//
+// Turns a finished task transcript into a reusable SKILL.md (the
+// Hermes self-improving-skill pattern). This module owns the
+// deterministic, LLM-free pieces so they can be unit-tested without a
+// network round-trip:
+//
+//   slugifySkill(title)        → a filesystem-safe skill name
+//   parseSynthOutput(text)     → { name, description, body } from raw
+//                                LLM output
+//   assembleSkillDoc({...})    → a full SKILL.md (frontmatter + body)
+//
+// The single LLM call lives in synthesizeSkill() at the bottom; it
+// mirrors agent_memory.reflectOnce() (same provider adapters, same
+// no-tools text completion) but asks for a structured skill instead of
+// free-text lessons.
+
+import * as skills from '../skills.mjs';
+import { runTextCompletion } from './provider_adapters.mjs';
+import { redactSecrets, neutralizeRoleLabels } from './redact.mjs';
+
+const SECTION_RE = /^#{1,6}\s+/;
+const MAX_NAME_LEN = 48;
+const MAX_BODY_BYTES = 8 * 1024;
+
+// Re-export the shared secret redactor (mas/redact.mjs) so existing
+// callers of skill_synth.redactSecrets keep working while the single
+// implementation is shared with agent_memory.reflectOnce.
+export { redactSecrets };
+
+// Sanitise an agent-authored skill body before it is persisted and
+// later loaded into other agents' context: redact secrets, neutralise
+// the task-termination marker (so reference material can't drive the
+// router loop), strip control characters, and cap the size.
+export function sanitizeSkillBody(text) {
+  let s = redactSecrets(text);
+  s = s.replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]');
+  // Strip control characters except tab/newline/carriage-return.
+  s = s.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
+  if (Buffer.byteLength(s, 'utf8') > MAX_BODY_BYTES) {
+    s = Buffer.from(s, 'utf8').subarray(0, MAX_BODY_BYTES).toString('utf8').replace(/\uFFFD+$/, '') + '\n\n…[truncated]';
+  }
+  return s;
+}
+
+// Sanitise the one-line description (it lands in every agent's system
+// prompt via the skills index): redact, collapse to a single line,
+// neutralise the marker, cap to 120 chars.
+export function sanitizeDescription(text) {
+  return redactSecrets(text)
+    .replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]')
+    .replace(/[\u0000-\u001F\u007F]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 120);
+}
+
+// Lowercase, collapse every run of non-alphanumerics into a single
+// dash, and strip leading/trailing dashes. Empty input (or input with
+// no alphanumerics) falls back to "skill" so a write always has a
+// valid target name.
+export function slugifySkill(title) {
+  const slug = String(title || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_NAME_LEN)
+    .replace(/-+$/g, '');
+  return slug || 'skill';
+}
+
+// Parse the model's reply into { name, description, body }. The prompt
+// asks for two leading `name:` / `description:` lines followed by the
+// `## When to Use / ## Procedure / ## Pitfalls / ## Verification`
+// sections — but models drift, so we degrade gracefully: when the
+// leading lines are missing we derive the name from the first heading
+// and leave the description empty. `body` always begins at the first
+// markdown heading (the section content), with the name/description
+// header stripped.
+export function parseSynthOutput(text) {
+  const raw = String(text || '').replace(/^/, '').trim();
+  const lines = raw.split(/\r?\n/);
+
+  let name = '';
+  let description = '';
+  let bodyStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (SECTION_RE.test(line)) { bodyStart = i; break; }
+    const nameM = /^name\s*:\s*(.+)$/i.exec(line.trim());
+    if (nameM && !name) { name = nameM[1].trim(); bodyStart = i + 1; continue; }
+    const descM = /^description\s*:\s*(.+)$/i.exec(line.trim());
+    if (descM && !description) { description = descM[1].trim(); bodyStart = i + 1; continue; }
+  }
+
+  const body = lines.slice(bodyStart).join('\n').replace(/^(?:\r?\n)+/, '').trimEnd();
+
+  // No explicit name → derive it from the first heading in the body.
+  if (!name) {
+    const firstHeading = body.split(/\r?\n/).find((l) => SECTION_RE.test(l));
+    if (firstHeading) name = firstHeading.replace(SECTION_RE, '').trim();
+  }
+
+  return { name: slugifySkill(name), description, body };
+}
+
+// Build a complete SKILL.md: a flat-YAML frontmatter block followed by
+// the skill body. The frontmatter shape round-trips through
+// skills.parseFrontmatter(). `ts` is injected (not read from the clock)
+// so the output is deterministic and testable.
+export function assembleSkillDoc({ name, description = '', createdBy = 'agent', sourceTask = '', body = '', version = 1, ts = new Date() } = {}) {
+  const date = (ts instanceof Date ? ts : new Date(ts)).toISOString().slice(0, 10);
+  const fm = [
+    '---',
+    `name: ${escapeYaml(stripControl(name))}`,
+    `description: ${escapeYaml(description)}`,
+    `version: ${version}`,
+    `created_by: ${createdBy}`,
+  ];
+  if (sourceTask) fm.push(`source_task: ${sourceTask}`);
+  fm.push(`created_at: ${date}`, '---', '');
+  return `${fm.join('\n')}\n${String(body).trim()}\n`;
+}
+
+// Drop control characters (incl. newlines) from a single-line frontmatter
+// value so an embedded \n can't break out of its key into an injected one.
+function stripControl(v) {
+  return String(v ?? '').replace(/[\u0000-\u001f\u007f]/g, '');
+}
+
+// Quote a value only when it contains characters our flat parser would
+// otherwise choke on (a leading special char or an embedded colon).
+// Control characters (including newlines) are stripped first: a quoted
+// multi-line value still injects a frontmatter key because the parser
+// splits on physical lines, so the only safe move is to flatten to a
+// single line before deciding whether to quote.
+function escapeYaml(v) {
+  const s = stripControl(v);
+  if (s === '') return '';
+  if (/[:#]/.test(s) || /^[\s'">|&*!%@`-]/.test(s)) return `"${s.replace(/"/g, '\\"')}"`;
+  return s;
+}
+
+export class SkillSynthError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SkillSynthError';
+    this.code = code || 'SKILL_SYNTH_ERR';
+  }
+}
+
+// Run one synthesis LLM call for an agent that just finished a task and
+// return { name, description, doc } — a complete SKILL.md ready to
+// install — or null when the model produced nothing usable. Mirrors
+// agent_memory.reflectOnce(): same provider adapters, a pure text
+// completion with no tools advertised, the agent's own role as the
+// system prompt. The difference is the ASK — a reusable skill in a
+// fixed section layout instead of free-text lessons.
+export async function synthesizeSkill({ agent, task, apiKey, baseUrl, fetchImpl } = {}) {
+  if (!agent || !task) throw new SkillSynthError('agent and task are required', 'SKILL_SYNTH_BAD_INPUT');
+
+  // Redact secrets from the transcript BEFORE it leaves for the model,
+  // so a token pasted into the task never reaches the LLM or the file.
+  const transcript = redactSecrets(
+    (Array.isArray(task.turns) ? task.turns : [])
+      .map((t) => {
+        const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
+        // Defang any forged role label inside the (model-controlled) body
+        // so a turn can't inject its own [System]/[User] authority line.
+        return `[${who}] ${neutralizeRoleLabels(t.text || '')}`;
+      })
+      .join('\n\n') || '(no turns)'
+  );
+
+  const userMessage =
+    `You just finished task "${task.title || '(untitled)'}" (id ${task.id}). Here is the full transcript:\n\n` +
+    transcript +
+    `\n\nDistil this into a REUSABLE skill that a future agent could load to handle a similar task faster. ` +
+    `Reply in EXACTLY this format and nothing else:\n\n` +
+    `name: <short kebab-case skill name>\n` +
+    `description: <one line, ≤ 120 chars, describing WHEN this skill applies>\n\n` +
+    `## When to Use\n<bullet conditions that signal this skill is relevant>\n\n` +
+    `## Procedure\n<numbered, concrete steps — real file paths / commands where known>\n\n` +
+    `## Pitfalls\n<gotchas and dead-ends you hit, so next time they're avoided>\n\n` +
+    `## Verification\n<how to confirm the task actually succeeded>\n\n` +
+    `Be concrete and specific to what happened. If the task was too trivial to be worth a reusable skill, reply with the single word NONE.`;
+
+  const text = (await runTextCompletion({
+    provider: agent.provider,
+    model: agent.model,
+    system: agent.role || '',
+    userMessage,
+    apiKey,
+    baseUrl,
+    fetchImpl,
+  })).trim();
+  if (!text || /^none\b/i.test(text)) return null;
+
+  const parsed = parseSynthOutput(text);
+  const description = sanitizeDescription(parsed.description);
+  const body = sanitizeSkillBody(parsed.body);
+  if (!body.trim()) return null;
+  const doc = assembleSkillDoc({ name: parsed.name, description, createdBy: 'agent', sourceTask: task.id, body });
+  return { name: parsed.name, description, body, doc, sourceTask: task.id };
+}
+
+// Install a synthesised skill without ever clobbering a human-authored
+// one: reserveSynthName picks a collision-free target (or our own prior
+// agent skill, which we then version-bump). Body/description are
+// re-sanitised here too so a direct caller (CLI/router) can't bypass
+// the redaction + cap. Returns { skill, path, version }.
+export function installSynthesized({ name, description = '', body = '', sourceTask = '', createdBy = 'agent' } = {}, configDir, ts = new Date()) {
+  // Slugify BEFORE reserving the name so a direct caller (CLI/router)
+  // can't smuggle a newline/colon into the filename or inject a second
+  // frontmatter key. parseSynthOutput already slugifies, but this path
+  // is also reachable directly with an arbitrary name.
+  const finalName = skills.reserveSynthName(slugifySkill(name), configDir);
+  const overwritingOwn = skills.skillExists(finalName, configDir);
+  const version = overwritingOwn ? skills.skillVersion(finalName, configDir) + 1 : 1;
+  const doc = assembleSkillDoc({
+    name: finalName,
+    description: sanitizeDescription(description),
+    createdBy,
+    sourceTask,
+    body: sanitizeSkillBody(body),
+    version,
+    ts,
+  });
+  const p = skills.installSkill(finalName, doc, configDir);
+  return { skill: finalName, path: p, version };
+}

package/mas/tool_runner.mjs

@@ -12,6 +12,7 @@ import * as bashTool from './tools/bash.mjs';
 import * as readTool from './tools/read.mjs';
 import * as writeTool from './tools/write.mjs';
 import * as grepTool from './tools/grep.mjs';
+import * as skillViewTool from './tools/skill_view.mjs';
 import * as audit from './audit.mjs';
 
 export class ToolError extends Error {
@@ -27,6 +28,7 @@ const TOOLS = {
   read: readTool,
   write: writeTool,
   grep: grepTool,
+  skill_view: skillViewTool,
 };
 
 const NOT_IMPLEMENTED_TOOLS = ['web_search', 'web_fetch', 'slack_post'];
@@ -55,11 +57,19 @@ export function knownTool(name) {
 // the caller can surface a structured error back to the LLM rather than
 // silently dropping the call.
 //
+// Tools that mutate state / run arbitrary code. When an `approve` hook is
+// supplied (e.g. backed by the gateway's remote exec-approval), these are
+// gated on a human decision before they run; read-only tools are not.
+const SENSITIVE_TOOLS = new Set(['bash', 'write']);
+
 // opts.cwd — where bash/read/write/grep root themselves; defaults to
 // process.cwd() so it can be overridden in tests.
 // opts.taskId — when set, every call is appended to the task's audit
 // log. Unit tests can omit it.
-export async function runTool({ agent, tool, args, taskId, configDir, cwd } = {}) {
+// opts.approve — optional async (call) => { approved, reason }. When
+// present, a sensitive tool call is held until it resolves; a non-approval
+// blocks the tool (returns a structured error instead of executing).
+export async function runTool({ agent, tool, args, taskId, configDir, cwd, approve } = {}) {
   if (!agent || !Array.isArray(agent.tools)) {
     throw new ToolError('agent record with .tools[] is required', 'TOOL_BAD_AGENT');
   }
@@ -76,9 +86,21 @@ export async function runTool({ agent, tool, args, taskId, configDir, cwd } = {}
     audit.append({ taskId, agent: agent.name, tool, args, result, ok: false, configDir });
     return result;
   }
+  // Human-in-the-loop gate for sensitive tools. A denial (or an erroring
+  // hook — fail closed) blocks execution and is audited like any result.
+  if (typeof approve === 'function' && SENSITIVE_TOOLS.has(tool)) {
+    let verdict;
+    try { verdict = await approve({ tool, args, agent: agent.name }); }
+    catch (err) { verdict = { approved: false, reason: `approval error: ${err?.message || err}` }; }
+    if (!verdict || !verdict.approved) {
+      const result = { ok: false, error: `tool "${tool}" denied by operator${verdict?.reason ? `: ${verdict.reason}` : ''}`, code: 'TOOL_DENIED_APPROVAL' };
+      audit.append({ taskId, agent: agent.name, tool, args, result, ok: false, configDir });
+      return result;
+    }
+  }
   let result;
   try {
-    result = await impl.exec(args || {}, { cwd: cwd || process.cwd() });
+    result = await impl.exec(args || {}, { cwd: cwd || process.cwd(), configDir });
   } catch (err) {
     result = { ok: false, error: `${tool} threw: ${err?.message || err}` };
   }

package/mas/tools/skill_view.mjs

@@ -0,0 +1,43 @@
+// skill_view tool — Phase 20.
+//
+// Read-only progressive-disclosure loader: the mention-router injects a
+// compact skills *index* (name + one-line summary) into the system
+// prompt, and the agent calls skill_view to pull the FULL text of a
+// skill only when it decides one is relevant. This keeps skill bodies
+// out of the prompt until they're actually needed.
+//
+// Unlike bash/read/write/grep this tool is rooted at the lazyclaw
+// config dir (where skills live), not the task cwd, so it takes
+// configDir from the tool-runner opts rather than cwd.
+
+import * as skills from '../../skills.mjs';
+
+export const NAME = 'skill_view';
+export const DESCRIPTION =
+  'Load the full text of a named skill from the skills index (its When-to-Use, Procedure, Pitfalls and Verification sections). Call this when a skill listed in the index looks relevant to the current task.';
+export const PARAMETERS = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', description: 'The skill name exactly as shown in the skills index.' },
+  },
+  required: ['name'],
+};
+
+export async function exec(args, { configDir } = {}) {
+  if (!args || typeof args.name !== 'string' || !args.name.trim()) {
+    return { ok: false, error: 'skill_view: name is required' };
+  }
+  const name = args.name.trim();
+  try {
+    const content = skills.loadSkill(name, configDir);
+    // Record the recall so the curator can age out never-used skills.
+    // Best-effort: a usage-write hiccup must never fail the tool call.
+    try {
+      const curator = await import('../../skills_curator.mjs');
+      curator.recordUsage(name, configDir, Date.now());
+    } catch { /* non-fatal */ }
+    return { ok: true, name, content };
+  } catch (err) {
+    return { ok: false, error: `skill_view: ${err?.message || err}` };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama, orchestrating multi-step LLM workflows, and running multi-agent Slack teams with cross-task memory. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",
@@ -48,6 +48,7 @@
     "browse.mjs",
     "sandbox.mjs",
     "skills_install.mjs",
+    "skills_curator.mjs",
     "cron.mjs",
     "loop-engine.mjs",
     "loops.mjs",
@@ -61,6 +62,7 @@
     "workflow/",
     "web/",
     "mas/",
+    "gateway/",
     "docs/multi-agent.md",
     "scripts/loop-worker.mjs",
     "README.md",

package/skills.mjs

@@ -38,24 +38,79 @@ export function listSkills(configDir = defaultConfigDir()) {
     .map(name => {
       const full = path.join(dir, name);
       const stat = fs.statSync(full);
-      const head = readFirstLine(full);
+      let content = '';
+      try { content = fs.readFileSync(full, 'utf8'); } catch { /* unreadable → empty */ }
+      const { meta, body } = parseFrontmatter(content);
+      // Prefer the agent-/author-supplied frontmatter description; fall
+      // back to the first markdown heading for legacy frontmatter-less
+      // skills so the index still reads sensibly.
+      const summary = (meta.description || firstHeading(body) || '').slice(0, 120);
       return {
         name: name.slice(0, -SKILL_EXT.length),
         path: full,
         bytes: stat.size,
         mtimeMs: stat.mtimeMs,
-        summary: head.replace(/^#+\s*/, '').slice(0, 120),
+        summary,
+        description: meta.description || '',
+        createdBy: meta.created_by || '',
+        version: meta.version || '',
       };
     })
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
-function readFirstLine(p) {
-  try {
-    const buf = fs.readFileSync(p, 'utf8');
-    const nl = buf.indexOf('\n');
-    return nl < 0 ? buf : buf.slice(0, nl);
-  } catch { return ''; }
+// Parse a leading YAML frontmatter block (--- … ---). Only the flat
+// `key: value` shape skills use is supported — no nested YAML — which
+// keeps us dependency-free. Returns { meta, body }; when no frontmatter
+// is present meta is {} and body is the untouched content.
+export function parseFrontmatter(content) {
+  const text = String(content ?? '');
+  if (!text.startsWith('---')) return { meta: {}, body: text };
+  // The opening fence must be its own line.
+  const afterOpen = text.slice(3);
+  if (!/^\r?\n/.test(afterOpen)) return { meta: {}, body: text };
+  const closeRe = /\r?\n---[ \t]*(?:\r?\n|$)/;
+  const m = closeRe.exec(afterOpen);
+  if (!m) return { meta: {}, body: text };
+  const block = afterOpen.slice(0, m.index);
+  // Drop blank lines between the closing fence and the first body line
+  // so callers can rely on body starting at real content.
+  const body = afterOpen.slice(m.index + m[0].length).replace(/^(?:\r?\n)+/, '');
+  const meta = {};
+  for (const line of block.split(/\r?\n/)) {
+    const mm = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim());
+    if (!mm) continue;
+    let val = mm[2].trim();
+    if (val.length >= 2 && val.startsWith('"') && val.endsWith('"')) {
+      // Symmetric with skill_synth's escapeYaml double-quote escaping.
+      val = val.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    } else if (val.length >= 2 && val.startsWith("'") && val.endsWith("'")) {
+      val = val.slice(1, -1);
+    }
+    meta[mm[1]] = val;
+  }
+  return { meta, body };
+}
+
+function firstHeading(body) {
+  for (const line of String(body || '').split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    return t.replace(/^#+\s*/, '');
+  }
+  return '';
+}
+
+// Compact "Level 0" recall index: one `- <name>: <summary>` line per
+// installed skill, sorted by name. Returns '' when no skills exist so
+// callers can inject it conditionally. This is what gets dropped into
+// the system prompt so the model knows which skills exist without
+// paying for their full bodies (progressive disclosure — the model
+// pulls a full skill on demand via the skill_view tool).
+export function skillsIndex(configDir = defaultConfigDir()) {
+  const skills = listSkills(configDir);
+  if (!skills.length) return '';
+  return skills.map((s) => `- ${s.name}: ${s.summary}`.trimEnd()).join('\n');
 }
 
 export function loadSkill(name, configDir = defaultConfigDir()) {
@@ -76,6 +131,44 @@ export function removeSkill(name, configDir = defaultConfigDir()) {
   if (fs.existsSync(p)) fs.unlinkSync(p);
 }
 
+export function skillExists(name, configDir = defaultConfigDir()) {
+  try { return fs.existsSync(skillPath(name, configDir)); }
+  catch { return false; }
+}
+
+// Read the integer `version` from a skill's frontmatter (0 when the
+// skill is missing or carries no version).
+export function skillVersion(name, configDir = defaultConfigDir()) {
+  try {
+    const { meta } = parseFrontmatter(fs.readFileSync(skillPath(name, configDir), 'utf8'));
+    return parseInt(meta.version, 10) || 0;
+  } catch { return 0; }
+}
+
+// Reserve a target name for an agent-synthesised skill that NEVER
+// clobbers a human-authored skill. If the slug is free, use it. If a
+// skill with that slug already exists AND it was itself agent-authored
+// (created_by: agent), reuse it — that's the self-improvement update
+// path. Otherwise the slug belongs to a human/curated skill, so we
+// append a numeric suffix and try again. This is the security boundary
+// that stops LLM-chosen slugs from overwriting trusted skills.
+export function reserveSynthName(name, configDir = defaultConfigDir()) {
+  const base = (name && String(name).trim()) || 'skill';
+  let candidate = base;
+  for (let i = 1; i < 1000; i++) {
+    let p;
+    try { p = skillPath(candidate, configDir); }
+    catch { return base; }
+    if (!fs.existsSync(p)) return candidate;
+    let createdBy = '';
+    try { createdBy = parseFrontmatter(fs.readFileSync(p, 'utf8')).meta.created_by || ''; }
+    catch { /* unreadable → treat as occupied */ }
+    if (createdBy === 'agent') return candidate;   // overwrite our own = improve
+    candidate = `${base}-${i}`;
+  }
+  return candidate;
+}
+
 /**
  * Compose the system prompt for a chat/agent invocation. Concatenates each
  * named skill's contents with a separator, in the order given. Returns null