@lh8ppl/claude-memory-kit 0.1.0

package/src/privacy.mjs

@@ -0,0 +1,21 @@
+// Shared privacy-tag sanitizer (FR-15, design §6.6). Used by every
+// disk-write hook handler (UserPromptSubmit, Stop) so the strip /
+// preserve rules are byte-identical between the prompt-capture and
+// turn-capture code paths.
+//
+// Contract:
+//   - <private>...</private> blocks (multiline + multi-occurrence) are
+//     REPLACED with the literal "[private content redacted]" placeholder.
+//     The original content never reaches any disk path.
+//   - <retain>...</retain> blocks are preserved VERBATIM (the tags
+//     themselves are kept) — the auto-extract subagent downstream
+//     uses them as force-save signals; stripping here would break
+//     that contract.
+
+const PRIVATE_RE = /<private>[\s\S]*?<\/private>/g;
+export const REDACTED_PLACEHOLDER = '[private content redacted]';
+
+export function sanitizePrivacyTags(text) {
+  if (typeof text !== 'string' || text === '') return text;
+  return text.replace(PRIVATE_RE, REDACTED_PLACEHOLDER);
+}

package/src/provenance.mjs

@@ -0,0 +1,217 @@
+// Provenance frontmatter writer + reader (Task 13, T-011).
+// Pure-functional formatting/parsing — no I/O. Two cooperating boundaries
+// share the same on-disk canonical shape so write → read → write is
+// byte-identical.
+//
+// Public surface:
+//   writeBullet({id, text, provenance}) → result
+//     - formats a 2-line bullet (bullet text on line 1, HTML-comment
+//       provenance on line 2) with all 7 required fields
+//   readBullet({bulletLine, commentLine}) → {id, text, provenance} | null
+//     - parses the pair; returns null on any non-match (graceful skip
+//       so callers iterating freeform markdown don't crash)
+//   parseBulletProvenance(commentLine) → provenance | null
+//     - just the comment parser; used by scratchpad.mjs's consolidator
+//       and (post-extraction) anywhere else that needs to read
+//       provenance from a freestanding comment line
+//
+// The 7 required fields per Task 13.2 / design §4:
+//   - id          (in bullet line as `(P-XXX)`, not duplicated in comment)
+//   - text        (the bullet body)
+//   - source      (file path, no inline line number)
+//   - source_line (positive integer; separate from `source`)
+//   - sha1
+//   - write       (enum)
+//   - trust       (enum)
+//   - at          (ISO 8601 UTC timestamp)
+//
+// Spec deviation: design §2.1's example uses `source: file.md:142` inline.
+// This module uses `source: file.md, source_line: 142` (separate fields)
+// per Task 13.2's explicit "7 required" enumeration. design.md §2.1 is
+// updated in this PR to match.
+//
+// Uses shared modules per CLAUDE.md "Shared modules" rule:
+//   tier-paths.mjs    — ID_PATTERN (validates the id format in the bullet line)
+//   result-shapes.mjs — ERROR_CATEGORIES, errorResult
+
+import { ID_PATTERN } from './tier-paths.mjs';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+
+const VALID_TRUST = new Set(['high', 'medium', 'low']);
+const VALID_WRITE_SOURCES = new Set([
+  'user-explicit',
+  'auto-extract',
+  'compressor',
+  'manual-edit',
+  'imported',
+]);
+const REQUIRED_PROVENANCE_FIELDS = [
+  'source',
+  'source_line',
+  'sha1',
+  'write',
+  'trust',
+  'at',
+];
+
+// PR-1 finding B2 was about newlines/colons in YAML-frontmatter scalar values.
+// Layer-3 review finding B3 is the same shape with `,` as the separator: the
+// HTML-comment provenance is `key: value, key: value, ...`, so a value
+// containing `,` would silently inject a fake field. A `source` of
+// `"Innocent, sha1: fake"` would round-trip as if it had an `sha1: fake`
+// field of its own. Defensive boundary check: reject these chars in scalar
+// provenance fields + the bullet text.
+//
+// `write` and `trust` are enums (already rejected if not in the allow-list);
+// `source_line` is a number (no string-injection possible).
+const UNSAFE_FOR_COMMENT = /[,\n\r]/;
+const UNSAFE_FOR_BULLET_TEXT = /[\n\r]/; // commas are fine in bullet text (line 1, not the comment)
+const FIELDS_TO_SANITIZE = ['source', 'sha1', 'at'];
+
+// Match the bullet line: `- (<id>) <text>`. The id pattern is the kit's
+// custom base32 alphabet from tier-paths.mjs; non-conforming ids are
+// treated as "not a kit bullet" by readBullet.
+const BULLET_RE = new RegExp(
+  `^- \\((${ID_PATTERN.source.replace(/^\^/, '').replace(/\$$/, '')})\\)\\s+(.+)$`,
+);
+
+// Match a provenance comment, tolerant of leading indentation.
+const COMMENT_RE = /^\s*<!--.*-->\s*$/;
+
+function validateBulletInput({ id, text, provenance }) {
+  const errors = [];
+
+  if (!id || typeof id !== 'string') {
+    errors.push('id: required, non-empty string');
+  } else if (!ID_PATTERN.test(id)) {
+    errors.push(
+      `id: must match the kit's citation-ID format (got ${JSON.stringify(id)})`,
+    );
+  }
+
+  if (!text || typeof text !== 'string' || !text.trim()) {
+    errors.push('text: required, non-empty string');
+  } else if (UNSAFE_FOR_BULLET_TEXT.test(text)) {
+    errors.push(
+      'text: must not contain newlines (would break the 2-line bullet+comment shape; see review finding B3)',
+    );
+  }
+
+  if (!provenance || typeof provenance !== 'object') {
+    errors.push(
+      'provenance: required object with source/source_line/sha1/write/trust/at',
+    );
+    return errors;
+  }
+
+  for (const f of REQUIRED_PROVENANCE_FIELDS) {
+    const v = provenance[f];
+    if (v === undefined || v === null || v === '') {
+      errors.push(`provenance.${f}: required, non-empty`);
+    }
+  }
+
+  if (
+    provenance.source_line !== undefined &&
+    provenance.source_line !== null &&
+    provenance.source_line !== ''
+  ) {
+    if (
+      typeof provenance.source_line !== 'number' ||
+      !Number.isInteger(provenance.source_line) ||
+      provenance.source_line < 1
+    ) {
+      errors.push(
+        'provenance.source_line: must be a positive integer (number type)',
+      );
+    }
+  }
+
+  if (provenance.trust && !VALID_TRUST.has(provenance.trust)) {
+    errors.push(
+      `provenance.trust: must be one of high/medium/low (got ${JSON.stringify(provenance.trust)})`,
+    );
+  }
+
+  if (provenance.write && !VALID_WRITE_SOURCES.has(provenance.write)) {
+    errors.push(
+      `provenance.write: must be one of user-explicit/auto-extract/compressor/manual-edit/imported (got ${JSON.stringify(provenance.write)})`,
+    );
+  }
+
+  // B3 defense: scalar string fields that land in the comment must not contain
+  // `,` / `\n` / `\r`. A `,` would silently spawn a fake field on read; a
+  // newline would break the single-line comment shape.
+  for (const f of FIELDS_TO_SANITIZE) {
+    const v = provenance[f];
+    if (typeof v === 'string' && UNSAFE_FOR_COMMENT.test(v)) {
+      errors.push(
+        `provenance.${f}: must not contain commas, newlines, or carriage returns ` +
+          '(comment-format injection risk; see review finding B3)',
+      );
+    }
+  }
+
+  return errors;
+}
+
+export function writeBullet(opts = {}) {
+  const errors = validateBulletInput(opts);
+  if (errors.length > 0) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors,
+    });
+  }
+
+  const { id, text, provenance: p } = opts;
+  const bullet = `- (${id}) ${text}`;
+  // Canonical field order (matches Task 13.2 enumeration):
+  //   source, source_line, sha1, write, trust, at
+  const comment =
+    `  <!-- source: ${p.source}, source_line: ${p.source_line},` +
+    ` sha1: ${p.sha1}, write: ${p.write}, trust: ${p.trust},` +
+    ` at: ${p.at} -->`;
+  return {
+    action: 'formatted',
+    id,
+    text,
+    bullet,
+    comment,
+    lines: `${bullet}\n${comment}`,
+  };
+}
+
+export function parseBulletProvenance(line) {
+  if (typeof line !== 'string') return null;
+  if (!COMMENT_RE.test(line)) return null;
+
+  const inner = line.replace(/^\s*<!--/, '').replace(/-->\s*$/, '');
+  const fields = {};
+  for (const part of inner.split(',')) {
+    const idx = part.indexOf(':');
+    if (idx === -1) continue;
+    const k = part.slice(0, idx).trim();
+    const v = part.slice(idx + 1).trim();
+    if (!k) continue;
+    fields[k] = v;
+  }
+  if (Object.keys(fields).length === 0) return null;
+
+  // Coerce numeric fields back to numbers for symmetric round-trip.
+  if (fields.source_line && /^\d+$/.test(fields.source_line)) {
+    fields.source_line = parseInt(fields.source_line, 10);
+  }
+  return fields;
+}
+
+export function readBullet(opts = {}) {
+  const { bulletLine, commentLine } = opts;
+  if (typeof bulletLine !== 'string') return null;
+  const m = bulletLine.match(BULLET_RE);
+  if (!m) return null;
+  const [, id, text] = m;
+  const provenance = parseBulletProvenance(commentLine);
+  if (!provenance) return null;
+  return { id, text, provenance };
+}

package/src/register-crons.mjs

@@ -0,0 +1,354 @@
+// Cross-platform host-scheduler registration (Task 33.2, T-028).
+//
+// Composes the platform-native scheduler primitive on each OS so the
+// daily-distill bin wrapper runs at 23:00 local time without users
+// learning crontab / launchd / schtasks themselves.
+//
+// Per design §8.6.2:
+//   Linux  → crontab pipe pattern (idempotent via grep -v + re-add)
+//   macOS  → launchd plist + launchctl bootstrap
+//   Windows → schtasks /Create /F (force-overwrite for idempotency)
+//
+// Per design §8.6.3:
+//   Node, not Python. The kit is already Node-only; adding Python means
+//   new test infra + install dep. spawnSync to the platform-native
+//   scheduler binary is the established kit pattern (compressor.mjs,
+//   capture-turn.mjs).
+//
+// Public boundary:
+//   registerCron({command, options?}) → {action, platform, command,
+//                                         executed, output, error?}
+//   unregisterCron({options?})        → same shape
+//   detectPlatform()                  → 'linux' | 'darwin' | 'win32'
+//
+// `options.dryRun: true` returns the platform-detected command WITHOUT
+// executing — used by tests + by users who want to inspect before
+// granting host permissions. Per the kit's autopilot stop boundary
+// (CLAUDE.md Workflow): "anything that touches the user's system beyond
+// the repo" requires user input. Defaults to dryRun=false; tests
+// always pass dryRun=true.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+
+// Canonical entry name across platforms. Used as the grep filter on
+// Linux, the LaunchAgent label on macOS, the Task Scheduler name on
+// Windows. Single source of truth — never construct ad-hoc names.
+export const CRON_ENTRY_NAME = 'cmk-daily-distill';
+
+// Task 34: second entry for weekly curate. Same naming convention.
+export const WEEKLY_ENTRY_NAME = 'cmk-weekly-curate';
+
+// Default schedule: 23:00 local time. Matches design §1.4 ("Daily 23:00
+// scripts/run-daily-distill.sh") + tasks.md 33.
+export const DEFAULT_SCHEDULE = { hour: 23, minute: 0 };
+
+// Default weekly schedule: Sunday 09:00 local time. Matches design §1.4
+// + tasks.md 34. dayOfWeek: 0=Sunday, 1=Monday, ..., 6=Saturday (cron + launchd convention).
+export const DEFAULT_WEEKLY_SCHEDULE = { hour: 9, minute: 0, dayOfWeek: 0 };
+
+// Map dayOfWeek (0-6, Sun=0) to schtasks /D abbreviation.
+const WIN_DAY_MAP = { 0: 'SUN', 1: 'MON', 2: 'TUE', 3: 'WED', 4: 'THU', 5: 'FRI', 6: 'SAT' };
+
+export function detectPlatform() {
+  return process.platform; // 'linux' | 'darwin' | 'win32' (other: bsd etc.)
+}
+
+function buildLinuxCronLine({ command, entryName, hour, minute, dayOfWeek }) {
+  // Standard 5-field cron syntax: minute hour day-of-month month day-of-week
+  // The trailing `# <entry-name>` comment is what makes the entry
+  // grep-able for idempotency + unregistration.
+  // Task 34: dayOfWeek (0-6, Sun=0) optional. When set, restricts the
+  // job to that weekday; when omitted, runs every day (`*`).
+  const dow = dayOfWeek === undefined || dayOfWeek === null ? '*' : String(dayOfWeek);
+  return `${minute} ${hour} * * ${dow} ${command} # ${entryName}`;
+}
+
+function macOsPlistPath(entryName) {
+  return join(homedir(), 'Library', 'LaunchAgents', `com.cmk.${entryName}.plist`);
+}
+
+function buildMacOsPlist({ command, entryName, hour, minute, dayOfWeek }) {
+  // Split command on whitespace for the ProgramArguments array.
+  // launchd doesn't honor shell quoting — each arg is its own element.
+  const args = command.split(/\s+/).filter(Boolean);
+  const argXml = args
+    .map((a) => `    <string>${escapeXml(a)}</string>`)
+    .join('\n');
+  const calendarLines = [
+    `    <key>Hour</key><integer>${hour}</integer>`,
+    `    <key>Minute</key><integer>${minute}</integer>`,
+  ];
+  if (dayOfWeek !== undefined && dayOfWeek !== null) {
+    // launchd Weekday: 0=Sunday, 1=Monday, ..., 6=Saturday (same as cron).
+    calendarLines.push(`    <key>Weekday</key><integer>${dayOfWeek}</integer>`);
+  }
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyLists-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    `  <key>Label</key><string>com.cmk.${entryName}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    argXml,
+    '  </array>',
+    '  <key>StartCalendarInterval</key>',
+    '  <dict>',
+    ...calendarLines,
+    '  </dict>',
+    '  <key>RunAtLoad</key><false/>',
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function buildWindowsSchtasks({ command, entryName, hour, minute, dayOfWeek }) {
+  // schtasks accepts /ST as HH:mm. /F forces re-create if the task
+  // already exists (idempotency primitive). /RL LIMITED (not HIGHEST)
+  // because daily distill doesn't need admin.
+  const time = `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+  // Escape inner double-quotes per schtasks /TR convention: `\"`.
+  // Task 33 B2 fix — pre-fix `/TR "${command}"` produced malformed
+  // nested quotes for any command containing `"` (typical when the
+  // command points at a Windows path with spaces). Skill-review caught
+  // this; the test fixture (cli-register-crons.test.js) didn't surface
+  // it because earlier tests only passed `'node bin.mjs'` (no quotes).
+  const escapedCommand = command.replace(/"/g, '\\"');
+  // Task 34: /SC WEEKLY /D <SUN|MON|...> for weekly cadence; /SC DAILY otherwise.
+  let scheduleFlags;
+  if (dayOfWeek !== undefined && dayOfWeek !== null) {
+    const day = WIN_DAY_MAP[dayOfWeek];
+    if (!day) {
+      throw new Error(`buildWindowsSchtasks: invalid dayOfWeek ${dayOfWeek}`);
+    }
+    scheduleFlags = `/SC WEEKLY /D ${day}`;
+  } else {
+    scheduleFlags = '/SC DAILY';
+  }
+  return `schtasks /Create /TN "${entryName}" ${scheduleFlags} /ST ${time} /TR "${escapedCommand}" /RL LIMITED /F`;
+}
+
+/**
+ * Register a cron entry on the current platform.
+ *
+ * @param {object} opts
+ * @param {string} opts.command  the command to run (typically a PATH-resolved bin name)
+ * @param {string} [opts.entryName]  the entry identifier — defaults to CRON_ENTRY_NAME ('cmk-daily-distill')
+ * @param {object} [opts.schedule]  {hour, minute, dayOfWeek?} — defaults to {23,0}; dayOfWeek (0-6, Sun=0) restricts to that weekday
+ * @param {boolean} [opts.dryRun]  if true, return the command(s) without executing
+ * @returns {object} {action, platform, executed, command, output, error?}
+ */
+export function registerCron(opts = {}) {
+  const errors = [];
+  if (!opts.command || typeof opts.command !== 'string') {
+    errors.push('command: required, non-empty string');
+  } else if (opts.command.includes("'")) {
+    // Task 33 I1 fix — the Linux cron line interpolates `command`
+    // into a single-quoted shell string (`echo '...'`). A command
+    // with an embedded single quote would break the quoting + open
+    // a shell-injection vector. Reject at the boundary; document
+    // the contract. Future caller wanting single quotes in their
+    // cron command needs to either escape POSIX-style ('\'') or
+    // we extend this helper with a sanitizer (v0.1.x candidate).
+    errors.push("command: must not contain single quotes (Linux cron-line shell-quoting contract)");
+  }
+  const entryName = opts.entryName ?? CRON_ENTRY_NAME;
+  if (!entryName || typeof entryName !== 'string' || !/^[a-zA-Z0-9_.-]+$/.test(entryName)) {
+    errors.push("entryName: must match /^[a-zA-Z0-9_.-]+$/ (used in shell + plist + schtasks identifiers)");
+  }
+  const {
+    hour = DEFAULT_SCHEDULE.hour,
+    minute = DEFAULT_SCHEDULE.minute,
+    dayOfWeek,
+  } = opts.schedule ?? {};
+  if (
+    !Number.isInteger(hour) || hour < 0 || hour > 23 ||
+    !Number.isInteger(minute) || minute < 0 || minute > 59
+  ) {
+    errors.push('schedule: {hour: 0-23, minute: 0-59}');
+  }
+  if (dayOfWeek !== undefined && dayOfWeek !== null) {
+    if (!Number.isInteger(dayOfWeek) || dayOfWeek < 0 || dayOfWeek > 6) {
+      errors.push('schedule.dayOfWeek: must be integer 0-6 (Sun=0)');
+    }
+  }
+  if (errors.length > 0) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors });
+  }
+
+  const platform = detectPlatform();
+  const dryRun = opts.dryRun === true;
+
+  if (platform === 'linux') {
+    const line = buildLinuxCronLine({ command: opts.command, entryName, hour, minute, dayOfWeek });
+    // Idempotent: list current crontab, strip any pre-existing entry
+    // by name, append the new line, pipe back.
+    const shellCmd = `(crontab -l 2>/dev/null | grep -v '${entryName}' ; echo '${line}') | crontab -`;
+    if (dryRun) {
+      return {
+        action: 'dry-run',
+        platform,
+        executed: false,
+        command: shellCmd,
+        output: '',
+      };
+    }
+    // timeout: 10s — scheduler operations are fast; a hung crontab
+    // command points at a broken host config and should fail loud.
+    const r = spawnSync('bash', ['-c', shellCmd], { encoding: 'utf8', timeout: 10_000 });
+    return {
+      action: r.status === 0 ? 'registered' : 'error',
+      platform,
+      executed: true,
+      command: shellCmd,
+      output: (r.stdout || '') + (r.stderr || ''),
+      ...(r.status === 0 ? {} : { error: `crontab exit ${r.status}` }),
+    };
+  }
+
+  if (platform === 'darwin') {
+    const plistPath = macOsPlistPath(entryName);
+    const plistContent = buildMacOsPlist({ command: opts.command, entryName, hour, minute, dayOfWeek });
+    if (dryRun) {
+      return {
+        action: 'dry-run',
+        platform,
+        executed: false,
+        command: `write ${plistPath} (${plistContent.length} bytes) + launchctl bootstrap gui/$UID ${plistPath}`,
+        output: plistContent,
+      };
+    }
+    mkdirSync(dirname(plistPath), { recursive: true });
+    writeFileSync(plistPath, plistContent, 'utf8');
+    // bootout first (in case a stale entry exists), then bootstrap.
+    // bootout exit code is non-zero if no entry is loaded — that's
+    // fine, we ignore it.
+    spawnSync('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}/com.cmk.${entryName}`], { encoding: 'utf8', timeout: 10_000 });
+    const r = spawnSync('launchctl', ['bootstrap', `gui/${process.getuid?.() ?? ''}`, plistPath], { encoding: 'utf8', timeout: 10_000 });
+    return {
+      action: r.status === 0 ? 'registered' : 'error',
+      platform,
+      executed: true,
+      command: `launchctl bootstrap gui/$UID ${plistPath}`,
+      output: (r.stdout || '') + (r.stderr || ''),
+      ...(r.status === 0 ? {} : { error: `launchctl exit ${r.status}` }),
+    };
+  }
+
+  if (platform === 'win32') {
+    const cmd = buildWindowsSchtasks({ command: opts.command, entryName, hour, minute, dayOfWeek });
+    if (dryRun) {
+      return {
+        action: 'dry-run',
+        platform,
+        executed: false,
+        command: cmd,
+        output: '',
+      };
+    }
+    // schtasks is a .exe; spawnSync handles it directly via shell:true
+    // (per the kit's Windows .cmd shim pattern in compressor.mjs).
+    const r = spawnSync(cmd, { shell: true, encoding: 'utf8', windowsHide: true, timeout: 10_000 });
+    return {
+      action: r.status === 0 ? 'registered' : 'error',
+      platform,
+      executed: true,
+      command: cmd,
+      output: (r.stdout || '') + (r.stderr || ''),
+      ...(r.status === 0 ? {} : { error: `schtasks exit ${r.status}` }),
+    };
+  }
+
+  return errorResult({
+    category: ERROR_CATEGORIES.SCHEMA,
+    errors: [`unsupported platform: ${platform}`],
+  });
+}
+
+/**
+ * Remove a cron entry on the current platform.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.entryName]  the entry to remove — defaults to CRON_ENTRY_NAME
+ * @param {boolean} [opts.dryRun]
+ */
+export function unregisterCron(opts = {}) {
+  const entryName = opts.entryName ?? CRON_ENTRY_NAME;
+  if (!entryName || typeof entryName !== 'string' || !/^[a-zA-Z0-9_.-]+$/.test(entryName)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: ["entryName: must match /^[a-zA-Z0-9_.-]+$/"],
+    });
+  }
+  const platform = detectPlatform();
+  const dryRun = opts.dryRun === true;
+
+  if (platform === 'linux') {
+    const shellCmd = `(crontab -l 2>/dev/null | grep -v '${entryName}') | crontab -`;
+    if (dryRun) {
+      return { action: 'dry-run', platform, executed: false, command: shellCmd, output: '' };
+    }
+    // timeout: 10s — scheduler operations are fast; a hung crontab
+    // command points at a broken host config and should fail loud.
+    const r = spawnSync('bash', ['-c', shellCmd], { encoding: 'utf8', timeout: 10_000 });
+    return {
+      action: r.status === 0 ? 'unregistered' : 'error',
+      platform, executed: true, command: shellCmd,
+      output: (r.stdout || '') + (r.stderr || ''),
+      ...(r.status === 0 ? {} : { error: `crontab exit ${r.status}` }),
+    };
+  }
+
+  if (platform === 'darwin') {
+    const plistPath = macOsPlistPath(entryName);
+    if (dryRun) {
+      return {
+        action: 'dry-run', platform, executed: false,
+        command: `launchctl bootout + rm ${plistPath}`, output: '',
+      };
+    }
+    spawnSync('launchctl', ['bootout', `gui/${process.getuid?.() ?? ''}/com.cmk.${entryName}`], { encoding: 'utf8', timeout: 10_000 });
+    if (existsSync(plistPath)) {
+      try { unlinkSync(plistPath); } catch { /* best-effort */ }
+    }
+    return {
+      action: 'unregistered', platform, executed: true,
+      command: `launchctl bootout + rm`, output: '',
+    };
+  }
+
+  if (platform === 'win32') {
+    const cmd = `schtasks /Delete /TN "${entryName}" /F`;
+    if (dryRun) {
+      return { action: 'dry-run', platform, executed: false, command: cmd, output: '' };
+    }
+    const r = spawnSync(cmd, { shell: true, encoding: 'utf8', windowsHide: true, timeout: 10_000 });
+    return {
+      // schtasks /Delete returns non-zero if the task didn't exist;
+      // we treat that as "already unregistered" (idempotent) since
+      // unregistering a non-existent entry is the intended end-state.
+      action: 'unregistered',
+      platform, executed: true, command: cmd,
+      output: (r.stdout || '') + (r.stderr || ''),
+    };
+  }
+
+  return errorResult({
+    category: ERROR_CATEGORIES.SCHEMA,
+    errors: [`unsupported platform: ${platform}`],
+  });
+}