mixdog 0.9.151 → 0.9.152

package/src/runtime/memory/lib/transcript-ingest.mjs

@@ -264,7 +264,7 @@ export function createTranscriptIngest({
     _transcriptOffsets = new Map()
   }
 
-  function initTranscriptWatcher() {
+  async function initTranscriptWatcher() {
     const root = projectsRoot()
     const SAFETY_POLL_MS = 5 * 60_000
     const DEBOUNCE_MS = 500
@@ -273,7 +273,6 @@ export function createTranscriptIngest({
     const watchers = []
     const intervals = []
     const polledFiles = new Set()
-    let safetySweepTimeout = null
 
     function isWatchable(relOrBase) {
       const base = path.basename(relOrBase)
@@ -345,14 +344,12 @@ export function createTranscriptIngest({
     async function safetySweep() {
       try {
         const active = await discoverActiveTranscripts()
-        for (const { path: fp } of active) ingestOne(fp)
+        await Promise.all(active.map(({ path: fp }) => ingestOne(fp)))
       } catch (e) {
         log(`[transcript-watch] safety sweep error: ${e.message}\n`)
       }
     }
 
-    safetySweepTimeout = setTimeout(safetySweep, 3_000)
-
     // fs.watch({recursive}) is only reliable on win32.
     // darwin: recursive option unreliable — use flat watch per-entry (glob dirs at start).
     // linux/WSL: recursive not supported — use fs.watchFile polling per file found via
@@ -429,9 +426,14 @@ export function createTranscriptIngest({
       intervals.push(setInterval(_patchedSweep, SAFETY_POLL_MS))
     }
 
+    // Runtime readiness includes the first active-transcript sweep. Without
+    // this barrier a lazy-started memory process can answer recall before the
+    // current session's persisted rows exist, causing automatic compaction to
+    // fail during the former three-second startup window.
+    await safetySweep()
+
     return {
       stop() {
-        if (safetySweepTimeout) { clearTimeout(safetySweepTimeout); safetySweepTimeout = null }
         for (const t of pendingByFile.values()) { try { clearTimeout(t) } catch {} }
         pendingByFile.clear()
         for (const i of intervals) { try { clearInterval(i) } catch {} }

package/src/runtime/memory/lib/transcript-ingest.test.mjs

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+
+import { createTranscriptIngest } from './transcript-ingest.mjs'
+
+test('transcript watcher initialization waits for the first active-session sweep', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'mixdog-transcript-watch-'))
+  const projectDir = path.join(root, 'project')
+  const sessionId = 'sess_readiness_regression'
+  const transcriptPath = path.join(projectDir, `${sessionId}.jsonl`)
+  const inserts = []
+  let offsets = '{}'
+  let watcher = null
+
+  try {
+    await mkdir(projectDir, { recursive: true })
+    await writeFile(transcriptPath, `${JSON.stringify({
+      type: 'user',
+      timestamp: new Date().toISOString(),
+      cwd: projectDir,
+      message: { content: 'persisted before memory readiness' },
+    })}\n`)
+
+    const ingest = createTranscriptIngest({
+      getDb: () => ({
+        async query(_sql, values) {
+          inserts.push(values)
+          return { rowCount: 1 }
+        },
+      }),
+      loadMeta: async () => offsets,
+      persistMeta: async (value) => { offsets = value },
+      projectsRoot: () => root,
+      resolveProjectId: () => 'project-readiness',
+      firstTextContent: (value) => String(value ?? ''),
+      cleanMemoryText: (value) => String(value ?? '').trim(),
+    })
+
+    await ingest.loadTranscriptOffsets()
+    watcher = await ingest.initTranscriptWatcher()
+
+    assert.equal(inserts.length, 1)
+    assert.equal(inserts[0][2], 'persisted before memory readiness')
+    assert.equal(inserts[0][4], sessionId)
+  } finally {
+    watcher?.stop()
+    await rm(root, { recursive: true, force: true })
+  }
+})

package/src/runtime/shared/child-spawn-gate.mjs

@@ -128,6 +128,19 @@ const SLOW_WAIT_MS = Math.max(
 const SLOW_WARN_THROTTLE_MS = 30000;
 
 let _lastSlowWarnAt = 0;
+let _lastFallbackWarnAt = 0;
+
+function _warnLeaseFallback(error, laneName) {
+  const now = Date.now();
+  if (now - _lastFallbackWarnAt < SLOW_WARN_THROTTLE_MS) return;
+  _lastFallbackWarnAt = now;
+  try {
+    process.stderr.write(
+      `[child-spawn-gate] lane=${laneName} machine spawn budget unavailable`
+      + ` (${error?.message || error}); using this process's bounded local lane\n`,
+    );
+  } catch { /* ignore */ }
+}
 
 function _maybeWarnSlow(waitedMs, laneName, lane) {
   if (waitedMs < SLOW_WAIT_MS) return;
@@ -175,6 +188,10 @@ export function acquire(signal = null, laneName = 'search', options = {}) {
       waitTimeoutMs,
     }).catch((error) => {
       if (error?.code !== 'ELEASEFALLBACK') throw error;
+      // Only a genuinely dead pool channel reaches here (the client re-arms
+      // while the link is alive). Say so loudly: from this point the cap is
+      // per-process, so N shards can hold N× the machine-wide budget.
+      _warnLeaseFallback(error, normalizedLaneName);
       return _acquireLocal(signal, normalizedLaneName, lane, ownerKey, waitTimeoutMs);
     });
   }

package/src/runtime/shared/child-spawn-remote.mjs

@@ -16,7 +16,32 @@ import { safeIpcSend } from './safe-ipc-send.mjs';
 const _pending = new Map(); // leaseId -> { grant, fail }
 let _sequence = 0;
 let _listening = false;
-let _broken = false;
+// "Lost" means the parent IPC link is actually gone — never merely slow. A
+// single timed-out or failed lease must NOT latch this process onto the
+// process-local lane: with several runtime shards that silently multiplies the
+// machine-wide child-spawn cap, which is exactly the Windows spawn storm this
+// gate exists to prevent.
+let _channelLost = false;
+// Bounded patience for a busy/recovering daemon. Each expiry re-arms while the
+// link is alive, so IPC latency keeps shards on the machine-wide budget.
+const LEASE_WAIT_EXTENSIONS = Math.max(
+  0,
+  Math.floor(Number(process.env.MIXDOG_SPAWN_LEASE_WAIT_EXTENSIONS) || 3),
+);
+const LEASE_WARN_THROTTLE_MS = 30_000;
+let _lastLeaseWarnAt = 0;
+
+function _warnSlowLease(budgetMs, extensionsLeft) {
+  const now = Date.now();
+  if (now - _lastLeaseWarnAt < LEASE_WARN_THROTTLE_MS) return;
+  _lastLeaseWarnAt = now;
+  try {
+    process.stderr.write(
+      `[child-spawn-remote] machine spawn lease pending >${budgetMs}ms; staying on the daemon budget`
+      + ` (${extensionsLeft} extension(s) left)\n`,
+    );
+  } catch { /* diagnostics only */ }
+}
 
 function _fallbackError(reason) {
   const error = new Error(`machine spawn budget unavailable (${reason}); using the local lane`);
@@ -24,6 +49,12 @@ function _fallbackError(reason) {
   return error;
 }
 
+function _leaseTimeoutError(reason) {
+  const error = new Error(`machine spawn budget did not answer (${reason}); spawn was not started`);
+  error.code = 'ESPAWNLEASETIMEOUT';
+  return error;
+}
+
 function _ensureListener() {
   if (_listening) return;
   _listening = true;
@@ -42,7 +73,7 @@ function _ensureListener() {
     pending.fail(error);
   });
   process.on('disconnect', () => {
-    _broken = true;
+    _channelLost = true;
     for (const [leaseId, pending] of [..._pending]) {
       _pending.delete(leaseId);
       pending.fail(_fallbackError('pool channel disconnected'));
@@ -50,9 +81,20 @@ function _ensureListener() {
   });
 }
 
+/**
+ * PID-accurate shard detection. MIXDOG_SESSION_RUNTIME_WORKER is inherited by
+ * every grandchild (tools, helpers, spawned nodes), so the plain flag cannot
+ * decide who owns a runtime IPC channel: only the process whose OWN pid matches
+ * the pid-scoped marker is a runtime shard. A grandchild therefore uses its own
+ * bounded local lane, and a real shard is never misread into it.
+ */
+export function isSessionRuntimeWorkerProcess(env = process.env, pid = process.pid) {
+  return String(env.MIXDOG_SESSION_RUNTIME_WORKER_PID || '') === String(pid);
+}
+
 export function remoteSpawnLeasesEnabled(env = process.env) {
-  return !_broken
-    && env.MIXDOG_SESSION_RUNTIME_WORKER === '1'
+  return !_channelLost
+    && isSessionRuntimeWorkerProcess(env)
     && env.MIXDOG_DISABLE_MACHINE_SPAWN_BUDGET !== '1'
     && typeof process.send === 'function'
     && process.connected === true;
@@ -91,7 +133,6 @@ export function acquireRemoteSpawnLease({ lane, ownerKey, signal, waitTimeoutMs
       if (settled) return;
       settled = true;
       cleanup();
-      if (error?.code === 'ELEASEFALLBACK') _broken = true;
       reject(error);
     };
     const grant = () => {
@@ -124,8 +165,29 @@ export function acquireRemoteSpawnLease({ lane, ownerKey, signal, waitTimeoutMs
     // The pool enforces the real waitTimeoutMs; this guard only covers a
     // parent that never answers (bug/kill) so a spawn can never hang forever.
     const budget = Math.max(1_000, Math.floor(Number(waitTimeoutMs) || 0)) + 5_000;
-    safety = setTimeout(() => fail(_fallbackError(`no lease response in ${budget}ms`)), budget);
-    safety.unref?.();
+    let extensionsLeft = LEASE_WAIT_EXTENSIONS;
+    const armSafety = () => {
+      safety = setTimeout(() => {
+        // A busy or recovering daemon is latency, not a broken budget
+        // authority: while the link is alive, keep waiting instead of dropping
+        // to a per-process lane that multiplies the machine-wide cap.
+        if (extensionsLeft > 0 && !_channelLost && process.connected === true) {
+          extensionsLeft -= 1;
+          _warnSlowLease(budget, extensionsLeft);
+          armSafety();
+          return;
+        }
+        // A still-connected authority may be wedged, but bypassing it would
+        // multiply the machine cap by the shard count. Fail this spawn instead;
+        // only an actually lost IPC channel is allowed to use the bounded
+        // process-local fallback lane.
+        fail(process.connected === true && !_channelLost
+          ? _leaseTimeoutError(`no lease response in ${budget}ms`)
+          : _fallbackError(`no lease response in ${budget}ms`));
+      }, budget);
+      safety.unref?.();
+    };
+    armSafety();
     const sent = safeIpcSend(process, {
       type: 'spawn-lease',
       leaseId,

package/src/runtime/shared/child-spawn-remote.test.mjs

@@ -0,0 +1,124 @@
+// Machine-wide child-spawn budget: every runtime shard must stay on the
+// daemon-owned gate. Two ways that silently breaks (and multiplies the cap by
+// the shard count) are covered here: an inherited env flag activating the
+// process-local lane in a grandchild, and one failed lease latching a shard
+// off the remote budget for the rest of its life.
+import assert from 'node:assert/strict';
+import { fork } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+import { isSessionRuntimeWorkerProcess } from './child-spawn-remote.mjs';
+
+const REMOTE_URL = new URL('./child-spawn-remote.mjs', import.meta.url).href;
+const GATE_URL = new URL('./child-spawn-gate.mjs', import.meta.url).href;
+
+const CHILD_SOURCE = `
+const inherited = process.env.STUB_PID_MODE === 'inherited';
+process.env.MIXDOG_SESSION_RUNTIME_WORKER = '1';
+// A grandchild inherits BOTH variables; only its own pid differs.
+process.env.MIXDOG_SESSION_RUNTIME_WORKER_PID = inherited
+  ? String(process.pid + 1)
+  : String(process.pid);
+const remote = await import(process.env.REMOTE_URL);
+const gate = await import(process.env.GATE_URL);
+const report = { enabled: remote.remoteSpawnLeasesEnabled(), mode: gate.snapshot().mode };
+if (!inherited) {
+  try {
+    await remote.acquireRemoteSpawnLease({ lane: 'search', ownerKey: 'test', waitTimeoutMs: 30000 });
+    report.firstLease = 'granted';
+  } catch (error) {
+    report.firstLease = String(error?.code || error?.message || error);
+  }
+  report.enabledAfterFailure = remote.remoteSpawnLeasesEnabled();
+  report.modeAfterFailure = gate.snapshot().mode;
+  const release = await remote.acquireRemoteSpawnLease({ lane: 'search', ownerKey: 'test', waitTimeoutMs: 30000 });
+  report.secondLease = typeof release === 'function' ? 'granted' : 'unexpected';
+  release();
+}
+process.send({ type: 'report', report });
+setTimeout(() => process.exit(0), 50).unref?.();
+`;
+
+async function runChild(mode, { onLease = () => {} } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), 'mixdog-spawn-remote-'));
+  const entry = join(dir, 'child.mjs');
+  await writeFile(entry, CHILD_SOURCE, 'utf8');
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = fork(entry, [], {
+        stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+        env: {
+          ...process.env,
+          STUB_PID_MODE: mode,
+          REMOTE_URL,
+          GATE_URL,
+        },
+      });
+      const timer = setTimeout(() => {
+        try { child.kill(); } catch {}
+        reject(new Error('child spawn-lease probe timed out'));
+      }, 20_000);
+      let stderr = '';
+      child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+      child.on('message', (message) => {
+        if (message?.type === 'spawn-lease') {
+          onLease(child, message);
+          return;
+        }
+        if (message?.type !== 'report') return;
+        clearTimeout(timer);
+        try { child.kill(); } catch {}
+        resolve({ ...message.report, stderr });
+      });
+      child.on('error', reject);
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test('only the pid-scoped runtime worker uses the machine-wide spawn budget', () => {
+  assert.equal(isSessionRuntimeWorkerProcess({ MIXDOG_SESSION_RUNTIME_WORKER_PID: '4242' }, 4242), true);
+  assert.equal(isSessionRuntimeWorkerProcess({ MIXDOG_SESSION_RUNTIME_WORKER_PID: '4242' }, 99), false);
+  // The inheritable flag alone can never claim the runtime IPC channel.
+  assert.equal(isSessionRuntimeWorkerProcess({ MIXDOG_SESSION_RUNTIME_WORKER: '1' }, 99), false);
+  assert.equal(isSessionRuntimeWorkerProcess({}, 99), false);
+});
+
+test('a grandchild that inherited the worker flag stays on its own local lane', async () => {
+  const report = await runChild('inherited');
+  assert.equal(report.enabled, false);
+  assert.equal(report.mode, 'local');
+});
+
+test('a failed lease never latches a shard off the machine-wide budget', async () => {
+  let leases = 0;
+  const report = await runChild('shard', {
+    onLease: (child, message) => {
+      leases += 1;
+      // First lease fails the way a momentarily unreachable pool does.
+      child.send(leases === 1
+        ? {
+          type: 'spawn-lease-result',
+          leaseId: message.leaseId,
+          ok: false,
+          error: 'pool channel unavailable',
+          code: 'ELEASEFALLBACK',
+        }
+        : { type: 'spawn-lease-result', leaseId: message.leaseId, ok: true });
+    },
+  });
+  assert.equal(report.enabled, true);
+  assert.equal(report.mode, 'remote-lease');
+  assert.equal(report.firstLease, 'ELEASEFALLBACK');
+  // Recovery: the shard is still on the daemon budget and the next lease is
+  // granted remotely instead of silently using a per-process lane.
+  assert.equal(report.enabledAfterFailure, true);
+  assert.equal(report.modeAfterFailure, 'remote-lease');
+  assert.equal(report.secondLease, 'granted');
+  assert.equal(leases, 2);
+});

package/src/runtime/shared/pristine-execution-contract.json

@@ -67,7 +67,8 @@
     "gemini": "GEMINI_API_KEY",
     "deepseek": "DEEPSEEK_API_KEY",
     "xai": "XAI_API_KEY",
-    "opencode-go": "OPENCODE_API_KEY"
+    "opencode-go": "OPENCODE_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY"
   },
   "personalStateCounters": [
     "behavioralStateFilesCopied",

package/src/runtime/shared/provider-api-key.mjs

@@ -13,6 +13,7 @@ export const AGENT_PROVIDER_ENV = Object.freeze({
   deepseek: 'DEEPSEEK_API_KEY',
   xai: 'XAI_API_KEY',
   'opencode-go': 'OPENCODE_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
 });
 
 export const AGENT_PROVIDER_ENV_ALIASES = Object.freeze({

package/src/runtime/shared/session-runtime-health.mjs

@@ -1,4 +1,5 @@
 import { normalize } from 'node:path';
+import { monitorEventLoopDelay } from 'node:perf_hooks';
 
 export const SESSION_RUNTIME_WORKER_UNHEALTHY_EVENT = 'mixdog:session-runtime-worker-unhealthy';
 
@@ -67,6 +68,96 @@ export function reportRuntimeDirectoryReadFailure(path, error, now = Date.now())
   });
 }
 
+// ── Per-shard event-loop lag ───────────────────────────────────────────────
+// Each runtime shard runs provider parsing, transcript projection and tool
+// results on its OWN event loop, so lag is the per-shard saturation signal the
+// daemon cannot see (it only measures itself). Lag is DIAGNOSTIC + ROUTING
+// input, never a kill signal: a saturated shard still owns accepted input and
+// in-flight turns, so the host quarantines it from NEW placement instead of
+// recycling it out from under that work.
+export const RUNTIME_LAG_DEFAULTS = Object.freeze({
+  intervalMs: 5_000,
+  warnP99Ms: 250,
+  degradedP99Ms: 2_000,
+  degradedSamples: 3,
+  recoverP99Ms: 750,
+});
+
+function lagMs(value) {
+  return Number.isFinite(value) ? Math.round(value / 1e6) : 0;
+}
+
+/**
+ * Sample this process's event-loop delay on a fixed interval.
+ * Returns a stop function; the timer is unref'd so it never holds the process.
+ */
+export function startRuntimeEventLoopLagMonitor({
+  intervalMs = RUNTIME_LAG_DEFAULTS.intervalMs,
+  resolution = 20,
+  onSample = () => {},
+} = {}) {
+  const histogram = monitorEventLoopDelay({ resolution });
+  histogram.enable();
+  const timer = setInterval(() => {
+    const sample = {
+      p50Ms: lagMs(histogram.percentile(50)),
+      p95Ms: lagMs(histogram.percentile(95)),
+      p99Ms: lagMs(histogram.percentile(99)),
+      maxMs: lagMs(histogram.max),
+      meanMs: lagMs(histogram.mean),
+      intervalMs,
+      at: Date.now(),
+    };
+    histogram.reset();
+    try { onSample(sample); } catch { /* telemetry must never throw upward */ }
+  }, intervalMs);
+  timer.unref?.();
+  return () => {
+    clearInterval(timer);
+    try { histogram.disable(); } catch {}
+  };
+}
+
+/**
+ * Hysteresis state machine over lag samples: a shard becomes `degraded` only
+ * after repeated sustained lag and recovers once it drops well below the
+ * trigger, so a single GC pause never quarantines a healthy shard.
+ */
+export function createRuntimeLagTracker(overrides = {}) {
+  const config = { ...RUNTIME_LAG_DEFAULTS, ...(overrides || {}) };
+  let consecutive = 0;
+  let degraded = false;
+  let sample = null;
+  return {
+    get config() { return config; },
+    get degraded() { return degraded; },
+    get sample() { return sample; },
+    record(next) {
+      sample = next && typeof next === 'object' ? next : null;
+      const p99 = Number(sample?.p99Ms) || 0;
+      if (p99 >= config.degradedP99Ms) {
+        consecutive += 1;
+        if (!degraded && consecutive >= config.degradedSamples) {
+          degraded = true;
+          return { degraded, changed: true, sample, consecutive };
+        }
+        return { degraded, changed: false, sample, consecutive };
+      }
+      consecutive = 0;
+      if (degraded && p99 <= config.recoverP99Ms) {
+        degraded = false;
+        return { degraded, changed: true, sample, consecutive };
+      }
+      return { degraded, changed: false, sample, consecutive };
+    },
+    reset() {
+      consecutive = 0;
+      degraded = false;
+      sample = null;
+    },
+  };
+}
+
 export function reportRuntimeAbortListenerPressure(warning, now = Date.now(), retainedListeners = 0) {
   if (!isCurrentSessionRuntimeWorker()) return false;
   if (!Number.isFinite(Number(retainedListeners)) || Number(retainedListeners) <= 50) {

package/src/runtime/shared/session-runtime-health.test.mjs

@@ -2,10 +2,63 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import {
+  createRuntimeLagTracker,
   recordRuntimeDirectoryReadSuccess,
   reportRuntimeAbortListenerPressure,
+  RUNTIME_LAG_DEFAULTS,
+  startRuntimeEventLoopLagMonitor,
 } from './session-runtime-health.mjs';
 
+test('sustained event-loop lag degrades a shard, a single spike does not', () => {
+  const tracker = createRuntimeLagTracker();
+  const spike = { p99Ms: RUNTIME_LAG_DEFAULTS.degradedP99Ms + 500 };
+  assert.equal(tracker.record(spike).degraded, false);
+  assert.equal(tracker.record(spike).degraded, false);
+  const degraded = tracker.record(spike);
+  assert.equal(degraded.degraded, true);
+  assert.equal(degraded.changed, true);
+  // Already degraded: no repeated transition.
+  assert.equal(tracker.record(spike).changed, false);
+  assert.equal(tracker.degraded, true);
+
+  // Hysteresis: still-elevated lag keeps the quarantine, a clean sample lifts it.
+  assert.equal(tracker.record({ p99Ms: RUNTIME_LAG_DEFAULTS.degradedP99Ms - 1 }).degraded, true);
+  const recovered = tracker.record({ p99Ms: 10 });
+  assert.equal(recovered.degraded, false);
+  assert.equal(recovered.changed, true);
+
+  // A fresh process starts from a clean slate.
+  tracker.record(spike);
+  tracker.reset();
+  assert.equal(tracker.degraded, false);
+  assert.equal(tracker.sample, null);
+});
+
+test('the event-loop lag monitor samples this process and stops cleanly', async () => {
+  const samples = [];
+  const stop = startRuntimeEventLoopLagMonitor({
+    intervalMs: 20,
+    onSample: (sample) => samples.push(sample),
+  });
+  try {
+    const deadline = Date.now() + 2_000;
+    while (samples.length === 0 && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  } finally {
+    stop();
+  }
+  assert.ok(samples.length > 0, 'monitor produced at least one sample');
+  const [sample] = samples;
+  for (const key of ['p50Ms', 'p95Ms', 'p99Ms', 'maxMs']) {
+    assert.equal(Number.isFinite(sample[key]), true, `${key} is numeric`);
+    assert.ok(sample[key] >= 0);
+  }
+  const seen = samples.length;
+  await new Promise((resolve) => setTimeout(resolve, 80));
+  assert.equal(samples.length, seen, 'no samples after stop');
+});
+
 test('repeated AbortSignal listener pressure marks only the session runtime worker unhealthy', () => {
   const originalRuntimeWorkerPid = process.env.MIXDOG_SESSION_RUNTIME_WORKER_PID;
   let detail = null;

package/src/runtime/shared/skill-document.mjs

@@ -0,0 +1,86 @@
+import { parseDocument } from 'yaml';
+
+const SKILL_FRONTMATTER_RE =
+  /^(?:\uFEFF)?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+const scalarText = (value, field) => {
+  if (typeof value !== 'string') {
+    throw new Error(`Skill ${field} must be a string.`);
+  }
+  return value.trim();
+};
+
+export function validateSkillName(value) {
+  const name = String(value || '').trim();
+  if (!name) throw new Error('Skill name is required.');
+  if (name.length > 64) throw new Error('Skill name must be 64 characters or fewer.');
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new Error('Skill name may contain only lowercase letters, numbers, and hyphens.');
+  }
+  if (name.startsWith('-') || name.endsWith('-') || name.includes('--')) {
+    throw new Error('Skill name cannot start or end with a hyphen or contain consecutive hyphens.');
+  }
+  return name;
+}
+
+export function validateSkillDescription(value) {
+  const description = String(value || '').trim();
+  if (!description) throw new Error('Skill trigger is required.');
+  if (description.length > 1024) {
+    throw new Error('Skill trigger must be 1024 characters or fewer.');
+  }
+  return description;
+}
+
+function parseFrontmatterDocument(markdown) {
+  const source = String(markdown || '');
+  const match = source.match(SKILL_FRONTMATTER_RE);
+  if (!match) throw new Error('SKILL.md must start with YAML frontmatter.');
+  const document = parseDocument(match[1], {
+    prettyErrors: false,
+    strict: true,
+    uniqueKeys: true,
+  });
+  if (document.errors.length) {
+    throw new Error(`Invalid SKILL.md frontmatter: ${document.errors[0].message}`);
+  }
+  const frontmatter = document.toJS({ maxAliasCount: 100 });
+  if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    throw new Error('SKILL.md frontmatter must be a YAML mapping.');
+  }
+  return { source, match, document, frontmatter };
+}
+
+export function parseSkillDocument(markdown) {
+  const parsed = parseFrontmatterDocument(markdown);
+  const name = validateSkillName(scalarText(parsed.frontmatter.name, 'name'));
+  const description = validateSkillDescription(
+    scalarText(parsed.frontmatter.description, 'description'),
+  );
+  return {
+    name,
+    description,
+    body: parsed.source.slice(parsed.match[0].length).replace(/^\r?\n/, ''),
+    frontmatter: parsed.frontmatter,
+  };
+}
+
+function renderSkillDocument(document, body) {
+  const instructions = String(body || '').replace(/\r\n/g, '\n').trim();
+  if (!instructions) throw new Error('Skill instructions are required.');
+  return `---\n${String(document).trimEnd()}\n---\n\n${instructions}\n`;
+}
+
+export function createSkillDocument({ name, description, body }) {
+  const document = parseDocument('');
+  document.set('name', validateSkillName(name));
+  document.set('description', validateSkillDescription(description));
+  return renderSkillDocument(document, body);
+}
+
+export function updateSkillDocument(markdown, { name, description, body }) {
+  const parsed = parseFrontmatterDocument(markdown);
+  parsed.document.set('name', validateSkillName(name));
+  parsed.document.set('description', validateSkillDescription(description));
+  return renderSkillDocument(parsed.document, body);
+}