@agilno-tech/rivet 0.1.0-alpha.0

package/src/commands/status.js

@@ -0,0 +1,224 @@
+import { execFileSync } from 'node:child_process';
+
+import { CliError, EXIT_CODES } from '../cli/output.js';
+import { createStatusServer } from '../status/server.js';
+
+const INSTANCE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const MAX_FIXTURE_BYTES = 512 * 1024;
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+const reflectApply = Reflect.apply;
+
+function fail(message, code = 'INVALID_INPUT') { throw new CliError(message, code); }
+
+function fixturePath(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 1_024 || value.includes('\0')
+    || value.startsWith('/') || value.includes('\\') || !/^[a-zA-Z0-9._/-]+$/.test(value)) fail('Status fixture path is invalid.');
+  const segments = value.split('/');
+  if (segments.some(segment => !segment || segment === '.' || segment === '..' || segment === '.git')) fail('Status fixture must be a repository-relative tracked file.');
+  return value;
+}
+
+function runGit(cwd, args, maximum = MAX_FIXTURE_BYTES + 1_024) {
+  return execFileSync('git', ['--literal-pathspecs', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', cwd, ...args], {
+    encoding: null,
+    maxBuffer: maximum,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 5_000,
+    windowsHide: true,
+  });
+}
+
+function readFixture(cwd, path) {
+  try {
+    const commit = runGit(cwd, ['rev-parse', '--verify', 'HEAD^{commit}'], 256).toString('ascii').trim();
+    if (!/^[0-9a-f]{40,64}$/.test(commit)) fail('Status fixture could not be read.', 'MISSING_CONFIGURATION');
+    const entry = runGit(cwd, ['ls-tree', '-z', '--full-tree', commit, '--', path], 4_096);
+    const match = /^(100644|100755) blob ([0-9a-f]{40,64})\t([^\0]+)\0$/.exec(entry.toString('utf8'));
+    if (!match || match[3] !== path) fail('Status fixture could not be read.', 'MISSING_CONFIGURATION');
+    const sizeText = runGit(cwd, ['cat-file', '-s', match[2]], 128).toString('ascii').trim();
+    if (!/^[1-9][0-9]{0,6}$/.test(sizeText)) fail('Status fixture is invalid.');
+    const size = Number(sizeText);
+    if (!Number.isSafeInteger(size) || size > MAX_FIXTURE_BYTES) fail('Status fixture is invalid.');
+    const bytes = runGit(cwd, ['cat-file', 'blob', match[2]], MAX_FIXTURE_BYTES + 1);
+    if (bytes.length !== size) fail('Status fixture is invalid.');
+    return JSON.parse(UTF8.decode(bytes));
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    fail('Status fixture could not be read.', 'MISSING_CONFIGURATION');
+  }
+}
+
+function validScript(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return false;
+  return input.version === 1 && ['success', 'retry', 'failed', 'blocked', 'budget-exhausted'].includes(input.kind)
+    && input.output && typeof input.output === 'object' && !Array.isArray(input.output)
+    && Array.isArray(input.output.evidence) && input.output.evidence.length <= 64
+    && input.output.evidence.every(value => typeof value === 'string' && INSTANCE_ID.test(value) && value.length <= 96)
+    && input.usage && typeof input.usage === 'object' && !Array.isArray(input.usage)
+    && Number.isSafeInteger(input.usage.tokens) && input.usage.tokens >= 0
+    && typeof input.usage.costUsd === 'number' && Number.isFinite(input.usage.costUsd) && input.usage.costUsd >= 0;
+}
+
+function fixtureState(instanceId, input, nowMs) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || input.schemaVersion !== 1
+    || !Array.isArray(input.scripts) || input.scripts.length === 0 || input.scripts.length > 64
+    || !input.scripts.every(validScript)) fail('Status fixture has an unsupported shape.');
+  const workerNodes = input.scripts.map((script, index) => {
+    const id = `fixture-worker-${index + 1}`;
+    const status = script.kind === 'success' ? 'completed' : script.kind === 'retry' ? 'corrective' : script.kind;
+    return {
+      id, parentId: 'manager-plan', owner: { role: 'worker', id: `${id}-owner` }, dependencies: ['manager-plan'],
+      requiredEvidenceTypes: script.output.evidence.map(() => 'test'), evidenceRefs: [...script.output.evidence], status,
+    };
+  });
+  const events = input.scripts.map((script, index) => ({
+    schemaVersion: 1,
+    eventId: `fixture-event-${index + 1}`,
+    graphId: instanceId,
+    nodeId: `fixture-worker-${index + 1}`,
+    sequence: index + 1,
+    timestamp: new Date(nowMs - ((input.scripts.length - index) * 1_000)).toISOString(),
+    actor: { role: 'worker', id: `fixture-worker-${index + 1}-owner` },
+    ...(script.kind === 'retry'
+      ? { type: 'retry', retryReason: 'fixture-retry' }
+      : { type: 'state-transition', priorState: 'running', newState: workerNodes[index].status }),
+  }));
+  const evidence = input.scripts.flatMap((script, index) => script.output.evidence.map(id => ({
+    id, nodeId: `fixture-worker-${index + 1}`, type: 'test', approvalState: script.kind === 'success' ? 'approved' : 'pending',
+  })));
+  const tokens = input.scripts.reduce((sum, script) => sum + script.usage.tokens, 0);
+  const costUsd = input.scripts.reduce((sum, script) => sum + script.usage.costUsd, 0).toFixed(2);
+  return Object.freeze({
+    schemaVersion: 1, version: 1, activated: true, terminal: null, startedAtMs: nowMs - (input.scripts.length * 1_000),
+    graph: {
+      schemaVersion: 1, id: instanceId, status: workerNodes.every(node => node.status === 'completed') ? 'completed' : 'running',
+      nodes: [
+        { id: 'boss-plan', owner: { role: 'boss', id: 'portfolio-boss' }, dependencies: [], requiredEvidenceTypes: [], evidenceRefs: [], status: 'completed' },
+        { id: 'manager-plan', parentId: 'boss-plan', owner: { role: 'manager', id: 'engineering-manager' }, dependencies: ['boss-plan'], requiredEvidenceTypes: [], evidenceRefs: [], status: 'completed' },
+        ...workerNodes,
+        { id: 'human-final', parentId: 'boss-plan', owner: { role: 'boss', id: 'portfolio-boss' }, dependencies: workerNodes.map(node => node.id), requiredEvidenceTypes: ['human-approval'], evidenceRefs: ['final-approval'], approvalGate: 'final-delivery', status: 'ready' },
+      ],
+    },
+    events, attempts: Object.fromEntries(workerNodes.map(node => [node.id, node.status === 'corrective' ? 2 : 1])),
+    launchIntents: {}, heartbeats: {}, evidence,
+    usage: { tokens, costUsd, retries: workerNodes.filter(node => node.status === 'corrective').length, timeMinutes: 0, taskLimit: input.scripts.length },
+    limits: { tokens: Math.max(tokens, 1), costUsd: String(Math.max(Number(costUsd), 1)), retries: 3, timeMinutes: 60, taskLimit: Math.max(input.scripts.length, 1) },
+  });
+}
+
+async function readPrivateInstance(instance, options = {}) {
+  if (!instance || typeof instance !== 'object' || typeof instance.acquire !== 'function' || typeof instance.read !== 'function') fail('Private orchestration instance is unavailable.', 'MISSING_CONFIGURATION');
+  if (options.signal?.aborted) fail('Private orchestration instance is unavailable.', 'MISSING_CONFIGURATION');
+  const lock = await instance.acquire({ signal: options.signal });
+  if (!lock || typeof lock.release !== 'function') fail('Private orchestration instance is unavailable.', 'MISSING_CONFIGURATION');
+  try {
+    if (options.signal?.aborted) fail('Private orchestration instance is unavailable.', 'MISSING_CONFIGURATION');
+    return await instance.read({ signal: options.signal });
+  } finally { await lock.release(); }
+}
+
+function serverSurface(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return null;
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 2 || keys.some(key => typeof key !== 'string' || !['start', 'close'].includes(key))) return null;
+  const copy = {};
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value') || typeof descriptor.value !== 'function') return null;
+    copy[key] = descriptor.value;
+  }
+  return Object.freeze(copy);
+}
+
+function validAddress(value, requestedPort) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return null;
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 3 || keys.some(key => typeof key !== 'string' || !['host', 'port', 'url'].includes(key))) return null;
+  const copy = {};
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) return null;
+    copy[key] = descriptor.value;
+  }
+  return copy.host === '127.0.0.1' && Number.isSafeInteger(copy.port) && copy.port >= 1 && copy.port <= 65_535
+    && (requestedPort === 0 || copy.port === requestedPort)
+    && copy.url === `http://127.0.0.1:${copy.port}` ? Object.freeze(copy) : null;
+}
+
+async function closeServer(close) {
+  try { await Reflect.apply(close, undefined, []); } catch { /* public CLI reports one fixed failure */ }
+}
+
+function waitForProcessSignal(signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise(resolvePromise => {
+    const finish = () => {
+      process.off('SIGINT', finish);
+      process.off('SIGTERM', finish);
+      signal?.removeEventListener?.('abort', finish);
+      resolvePromise();
+    };
+    process.once('SIGINT', finish);
+    process.once('SIGTERM', finish);
+    signal?.addEventListener?.('abort', finish, { once: true });
+  });
+}
+
+export async function statusCommand(parsed, dependencies) {
+  if (!parsed || parsed.command !== 'status' || parsed.subcommand !== null || !Array.isArray(parsed.operands)
+    || parsed.operands.length !== 1 || !INSTANCE_ID.test(parsed.operands[0]) || parsed.operands[0].length > 64
+    || !parsed.flags || Object.keys(parsed.flags).some(key => !['fixture', 'port', 'json'].includes(key))) fail('Status requires one explicit orchestration instance ID.');
+  const instanceId = parsed.operands[0];
+  const portValue = parsed.flags.port ?? '0';
+  if (typeof portValue !== 'string' || !/^(?:0|[1-9][0-9]{0,4})$/.test(portValue) || Number(portValue) > 65_535) fail('Status port is invalid.');
+  const context = dependencies?.status ?? {};
+  const now = typeof context.now === 'function' ? context.now : Date.now;
+  let readState;
+  if (parsed.flags.fixture !== undefined) {
+    const path = fixturePath(parsed.flags.fixture);
+    const fixture = readFixture(dependencies.cwd(), path);
+    const state = fixtureState(instanceId, fixture, now());
+    readState = async () => state;
+  } else {
+    if (typeof context.resolveInstance !== 'function') fail('Private orchestration is not configured.', 'MISSING_CONFIGURATION');
+    const instance = await context.resolveInstance(instanceId);
+    if (!instance || instance.id !== instanceId) fail('Private orchestration instance is unavailable.', 'MISSING_CONFIGURATION');
+    readState = options => readPrivateInstance(instance, options);
+  }
+  const factory = typeof context.createServer === 'function' ? context.createServer : createStatusServer;
+  let server;
+  try {
+    server = serverSurface(factory({ readState, now, limits: context.limits, pollIntervalMs: context.pollIntervalMs, readTimeoutMs: context.readTimeoutMs, maxSseClients: context.maxSseClients }));
+  } catch { fail('Status server is unavailable.', 'MISSING_CONFIGURATION'); }
+  if (!server) fail('Status server is unavailable.', 'MISSING_CONFIGURATION');
+  const requestedPort = Number(portValue);
+  let address;
+  try {
+    address = validAddress(await Reflect.apply(server.start, undefined, [{ port: requestedPort }]), requestedPort);
+    if (!address) throw new Error('invalid status address');
+  } catch {
+    await closeServer(server.close);
+    fail('Status server is unavailable.', 'MISSING_CONFIGURATION');
+  }
+  const waitFunction = typeof context.wait === 'function' ? context.wait : waitForProcessSignal;
+  const waitReceiver = typeof context.wait === 'function' ? context : undefined;
+  const wait = signal => reflectApply(waitFunction, waitReceiver, [signal]);
+  if (parsed.flags.json) {
+    try {
+      dependencies.output.json({ ok: true, command: 'status', instanceId, url: address.url });
+      if (typeof dependencies.registerStatusJsonLifecycle !== 'function') throw new Error('missing status lifecycle owner');
+      dependencies.registerStatusJsonLifecycle(wait, context.signal, server.close);
+    } catch {
+      await closeServer(server.close);
+      throw new CliError('Status server is unavailable.', 'MISSING_CONFIGURATION');
+    }
+    return EXIT_CODES.SUCCESS;
+  }
+  try {
+    dependencies.output.log(`Status: ${address.url}`);
+    await wait(context.signal);
+  } finally { await closeServer(server.close); }
+  return EXIT_CODES.SUCCESS;
+}

package/src/commands/support.js

@@ -0,0 +1,44 @@
+import { collectSupportBundle, resolveSupportProject } from '../support/bundle.js';
+import { saveSupportReport } from '../support/failure-report.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+
+export async function supportCommand(parsed, dependencies) {
+  if (parsed.operands.length || Object.keys(parsed.flags).some(key => !['project','probe-harnesses','save','json'].includes(key))) {
+    throw new CliError('Use rivet support [--project=<path>] [--probe-harnesses] [--save] [--json].', 'INVALID_INPUT');
+  }
+  const root = await resolveSupportProject(dependencies.cwd(), parsed.flags.project);
+  const controller = new AbortController(), abort = () => controller.abort();
+  process.on('SIGINT', abort);
+  process.on('SIGTERM', abort);
+  let result, savedReport;
+  try {
+    const options = {
+      environment: dependencies.env,
+      signal: controller.signal,
+      probeHarnesses: parsed.flags['probe-harnesses'] === true,
+      ...(dependencies.support?.diagnose ? {diagnose: dependencies.support.diagnose} : {}),
+      ...(dependencies.support?.discoverHarnesses ? {discoverHarnesses: dependencies.support.discoverHarnesses} : {}),
+    };
+    if (parsed.flags.save === true) {
+      try {
+        const saved = await saveSupportReport(root, options);
+        result = saved.report;
+        savedReport = {path: saved.path};
+      } catch {
+        throw new CliError('Support report could not be saved. Try rivet support --json to display the report.', 'INTERNAL_ERROR');
+      }
+    } else result = await collectSupportBundle(root, options);
+  } finally {
+    process.off('SIGINT', abort);
+    process.off('SIGTERM', abort);
+  }
+  if (parsed.flags.json) dependencies.output.json({ok: true, result, ...(savedReport ? {savedReport} : {})});
+  else {
+    dependencies.output.log(`Support collection: ${result.collection.status}. Configuration: ${result.configuration.status}. Readiness: ${result.readiness.status}.`);
+    if (savedReport) {
+      dependencies.output.log(`Support report saved: ${savedReport.path}`);
+      dependencies.output.log('Review the file before attaching it to an issue at https://github.com/Agilno-Tech/rivet/issues/new. Nothing was uploaded.');
+    } else dependencies.output.log('Save a shareable report with rivet support --save. Add --probe-harnesses to include local CLI capability checks.');
+  }
+  return EXIT_CODES.SUCCESS;
+}

package/src/commands/task-completion.js

@@ -0,0 +1,104 @@
+import { applyVerifiedTask } from '../feature/local-approval.js';
+import { createGitClient } from '../git/client.js';
+import { withTerminalInterruption } from '../cli/interrupt.js';
+import { CliError, EXIT_CODES, observeOutputErrors } from '../cli/output.js';
+import { deliveryCommand } from './delivery.js';
+import { invokeFeature } from './feature.js';
+
+function fail(message, code = 'INVALID_INPUT') { throw new CliError(message, code); }
+function visible(value) { return String(value).replace(/[\u0000-\u001f\u007f\u009b]/g, character => `\\u${character.codePointAt(0).toString(16).padStart(4,'0')}`); }
+function displayPatch(value) { return String(value).split('\n').map(visible).join('\n'); }
+const completionChoices = [
+  {value:'review',label:'Review changes'},
+  {value:'pull-request',label:'Pull-request delivery (recommended for team review)'},
+  {value:'local',label:'Apply locally (update the current default branch; no push)'},
+  {value:'leave',label:'Leave for later'},
+];
+
+export async function finishTask(project, record, dependencies, options = {}) {
+  let failed = false;
+  const unobserve = observeOutputErrors(dependencies.output,()=>{failed=true;});
+  const assertDisplay = () => { if(failed) fail('Final review output failed. Nothing further was approved. Retry in a working terminal.', 'REPOSITORY_CONFLICT'); };
+  try { return await finishTaskAction(project,record,dependencies,{...options,assertDisplay}); }
+  finally { unobserve?.(); }
+}
+
+async function finishTaskAction(project, record, dependencies, options) {
+  if (!['awaiting-final-approval', 'completed'].includes(record.status)) fail('This task has no verified result ready for final review. Use rivet task status.', 'REPOSITORY_CONFLICT');
+  if (dependencies.terminalIsInteractive?.() !== true) fail('Run rivet task approve in an interactive terminal for final review.');
+  let reviewedStatus;
+  if (record.status !== 'completed') {
+    const status = await invokeFeature(dependencies.work, 'status', {project: project.root, runId: record.runId});
+    reviewedStatus = status;
+    if (status.deliveryReady !== true) fail('Final review requires current passing checks and a clean verified checkout. Use rivet task status.', 'REPOSITORY_CONFLICT');
+    dependencies.output.log('Changes passed checks and are ready for your review.');
+    dependencies.output.log(`Verified commit: ${visible(status.checkout.acceptedCommit)}`);
+    dependencies.output.log(`Integration checkout: ${visible(status.checkout.path)}`);
+    for (const path of status.verification.changedPaths) dependencies.output.log(`Changed: ${visible(path)}`);
+    for (const check of status.verification.checks) dependencies.output.log(`Check: ${visible(check.id)} ${visible(check.status)}`);
+  }
+  options.assertDisplay();
+  const finish = async signal => {
+    let choice = record.status === 'completed' ? 'local' : await dependencies.taskApprovalPrompt({
+      type: 'select', signal, message: 'How would you like to finish this task?',
+      choices: completionChoices,
+    });
+    options.assertDisplay();
+    while (choice === 'review') {
+      signal.throwIfAborted();
+      const baseline = reviewedStatus?.run?.featurePlan?.baselineCommit ?? record.featurePlan?.baselineCommit;
+      const tip = reviewedStatus?.checkout?.acceptedCommit;
+      const gitClient = await createGitClient({gitExecutable: await dependencies.resolveCommandExecutable('git')});
+      try {
+        const diff = await gitClient.reviewDiff(project.root,{fromSha:baseline,toSha:tip});
+        dependencies.output.log(diff.patch ? displayPatch(diff.patch) : 'No file changes.');
+        if(diff.truncated) dependencies.output.log('Diff preview was truncated. Inspect the integration checkout before approval.');
+      } catch {
+        fail('Could not display the complete diff. Inspect the integration checkout shown above, then retry rivet task approve. No changes were applied.', 'REPOSITORY_CONFLICT');
+      }
+      options.assertDisplay();
+      choice = await dependencies.taskApprovalPrompt({type:'select',signal,message:'How would you like to finish this task?',choices:completionChoices});
+      options.assertDisplay();
+    }
+    if (choice === 'leave' || choice === null || choice === undefined) { dependencies.output.log('Final review cancelled. Work is saved for later. Continue with rivet task resume.'); return EXIT_CODES.SUCCESS; }
+    if (choice === 'pull-request') {
+      signal.throwIfAborted();
+      const result = await deliveryCommand({command:'delivery',subcommand:'prepare',operands:[],flags:{project:project.root,run:record.runId}}, dependencies);
+      if (result === EXIT_CODES.SUCCESS) {
+        dependencies.output.log(`Delivery prepared locally. From project ${visible(project.root)}, publish and create the review with separate approvals:`);
+        dependencies.output.log(`rivet delivery publish --run=${record.runId}`);
+        dependencies.output.log(`rivet delivery review --run=${record.runId}`);
+        dependencies.output.log('No remote write or merge has been approved by this selection.');
+      }
+      return result;
+    }
+    if (choice !== 'local') fail('Select local application or pull-request delivery.');
+    const gitClient = await createGitClient({gitExecutable: await dependencies.resolveCommandExecutable('git')});
+    let outputFailed = false;
+    const unobserve = observeOutputErrors(dependencies.output, () => { outputFailed = true; });
+    try {
+      const result = await applyVerifiedTask({project:project.root,runId:record.runId,gitClient,signal,confirm:async preview => {
+        try {
+          dependencies.output.log(`Apply to local branch: ${visible(preview.targetBranch)}`);
+          dependencies.output.log(`From: ${visible(preview.baselineCommit)}`);
+          dependencies.output.log(`To: ${visible(preview.commitSha)}`);
+          for (const path of preview.changedPaths) dependencies.output.log(`Changed: ${visible(path)}`);
+          for (const check of preview.checks) dependencies.output.log(`Check: ${visible(check.id)} ${visible(check.status)}`);
+          dependencies.output.log('This updates the original checkout using a fast-forward only. It does not push or deploy.');
+        } catch { fail('Could not display the local application preview. Nothing was approved.', 'REPOSITORY_CONFLICT'); }
+        if (outputFailed || signal.aborted) return false;
+        const approved = await dependencies.confirmTaskApplication(preview,{signal});
+        options.assertDisplay();
+        return approved === true && !outputFailed && !signal.aborted;
+      }});
+      dependencies.output.log(`Local application: ${visible(result.status)}.`);
+      if (result.nextAction) dependencies.output.log(visible(result.nextAction));
+      return EXIT_CODES.SUCCESS;
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      fail(error?.safeMessage ?? 'Local application could not complete safely. Inspect task status and preserve the checkouts.', 'REPOSITORY_CONFLICT');
+    } finally {unobserve?.();}
+  };
+  return options.signal ? finish(options.signal) : withTerminalInterruption(finish);
+}
+

package/src/commands/uninstall.js

@@ -0,0 +1,234 @@
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { CliError, EXIT_CODES } from '../cli/output.js';
+import {
+  checkForUpdate,
+  installedSkillName,
+  getAgentNames,
+  getMandatoryNames,
+  getSkillNames,
+  resolveTargetLocation,
+  withPinnedTargetDirectory,
+} from './install.js';
+
+function lstatIfExists(path, fs) {
+  try {
+    return fs.lstatSync(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function fileIdentity(status) {
+  return Object.freeze({ dev: status.dev, ino: status.ino });
+}
+
+function sameFileIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function allocateQuarantineName(fs) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const name = `.rivet-uninstall-${randomUUID()}`;
+    if (!lstatIfExists(name, fs)) return name;
+  }
+  throw new CliError('Could not allocate a private uninstall entry.', 'REPOSITORY_CONFLICT');
+}
+
+function restoreQuarantine(fs, quarantineName, destinationName, expectedIdentity, requireIdentity = true) {
+  const quarantineStatus = lstatIfExists(quarantineName, fs);
+  if (!quarantineStatus) return false;
+  if (requireIdentity && !sameFileIdentity(expectedIdentity, quarantineStatus)) return false;
+  if (lstatIfExists(destinationName, fs)) return false;
+  fs.renameSync(quarantineName, destinationName);
+  return true;
+}
+
+function removeSelectedEntry(name, fs) {
+  const selectedStatus = lstatIfExists(name, fs);
+  if (!selectedStatus) return false;
+  if (selectedStatus.isSymbolicLink()) {
+    throw new CliError('Managed uninstall entry is a symbolic link.', 'REPOSITORY_CONFLICT');
+  }
+
+  const expectedIdentity = fileIdentity(selectedStatus);
+  const quarantineName = allocateQuarantineName(fs);
+  fs.renameSync(name, quarantineName);
+
+  const quarantinedStatus = lstatIfExists(quarantineName, fs);
+  if (!quarantinedStatus || !sameFileIdentity(expectedIdentity, quarantinedStatus)) {
+    try {
+      restoreQuarantine(fs, quarantineName, name, expectedIdentity, false);
+    } catch {
+      // A mismatched entry is never recursively removed.
+    }
+    throw new CliError('Managed uninstall entry changed during validation.', 'REPOSITORY_CONFLICT');
+  }
+
+  try {
+    fs.rmSync(quarantineName, { recursive: true, force: false });
+  } catch (error) {
+    try {
+      restoreQuarantine(fs, quarantineName, name, expectedIdentity, true);
+    } catch {
+      // Best-effort rollback preserves a matching quarantine for manual recovery.
+    }
+    throw error;
+  }
+  return true;
+}
+
+async function resolveTargets(parsed, dependencies) {
+  if (parsed.flags.claude && parsed.flags.codex) return ['claude', 'codex'];
+  if (parsed.flags.claude) return ['claude'];
+  if (parsed.flags.codex) return ['codex'];
+
+  const target = parsed.flags.target;
+  if (typeof target === 'string') {
+    const normalized = target.toLowerCase();
+    if (normalized === 'both') return ['claude', 'codex'];
+    if (normalized === 'claude' || normalized === 'codex') return [normalized];
+  }
+  if (target) {
+    throw new CliError("Invalid --target value. Use 'claude', 'codex', or 'both'.", 'INVALID_INPUT');
+  }
+
+  try {
+    const selected = await dependencies.prompt({
+      message: 'Select destinations to uninstall:',
+      choices: [
+        { name: 'Claude Code', value: 'claude', checked: true },
+        { name: 'Codex', value: 'codex', checked: true },
+      ],
+    });
+    if (selected.length === 0) {
+      dependencies.output.log('No destinations selected. Nothing to do.');
+      return null;
+    }
+    return selected;
+  } catch {
+    dependencies.output.log('\nCancelled.');
+    return null;
+  }
+}
+
+export async function uninstall(parsed, dependencies) {
+  if (parsed.flags['project-runtime']) {
+    const { projectRuntimeInstall } = await import('../install/project-runtime.js');
+    return projectRuntimeInstall(parsed, dependencies);
+  }
+  if (parsed.flags.minimal) {
+    const { managedInstall } = await import('../install/managed.js');
+    return managedInstall(parsed, dependencies);
+  }
+  const { fs, output, prompt } = dependencies;
+  const targets = await resolveTargets(parsed, dependencies);
+  if (!targets) return EXIT_CODES.SUCCESS;
+  const targetDirs = targets.map(target => resolveTargetLocation(target, parsed, dependencies));
+
+  for (const targetLocation of targetDirs) {
+    targetLocation.identity = targetLocation.guard.assertPath(targetLocation.dir);
+  }
+
+  const existingTargetDirs = targetDirs.filter(({ dir }) => fs.existsSync(dir));
+  if (existingTargetDirs.length === 0) {
+    output.warn('Warning: skills directories not found for selected targets. Nothing to uninstall.');
+    return EXIT_CODES.SUCCESS;
+  }
+
+  const mandatorySet = new Set(getMandatoryNames(dependencies).map(installedSkillName));
+  const existingOptional = new Set();
+  const existingMandatory = new Set();
+  const packageNames = [
+    ...getSkillNames(dependencies),
+    ...getAgentNames(dependencies),
+    ...getMandatoryNames(dependencies),
+  ].map(installedSkillName);
+  for (const { dir } of existingTargetDirs) {
+    for (const name of packageNames) {
+      if (fs.existsSync(join(dir, name))) {
+        if (mandatorySet.has(name)) existingMandatory.add(name);
+        else existingOptional.add(name);
+      }
+    }
+  }
+
+  const allOptional = [...existingOptional];
+  const allMandatory = [...existingMandatory];
+  if (allOptional.length === 0 && allMandatory.length === 0) {
+    output.warn("Warning: None of this package's skills were found at selected targets. Nothing removed.");
+    return EXIT_CODES.SUCCESS;
+  }
+
+  let selectedOptional;
+  let removeMandatory = false;
+  if (parsed.flags.all) {
+    selectedOptional = allOptional;
+    removeMandatory = true;
+  } else {
+    if (allMandatory.length > 0) {
+      output.log('\nMandatory skills (included in uninstall by default):');
+      allMandatory.forEach(name => output.log(`  [required]  ${name}`));
+    }
+    try {
+      const choices = [
+        ...allMandatory.map(name => ({ name: `${name} [mandatory]`, value: `mandatory:${name}`, checked: true })),
+        ...allOptional.map(name => ({ name, value: name, checked: true })),
+      ];
+      const raw = await prompt({
+        message: 'Select skills to uninstall (mandatory included by default):',
+        choices,
+      });
+      selectedOptional = raw.filter(value => !value.startsWith('mandatory:')).map(value => value);
+      removeMandatory = raw.some(value => value.startsWith('mandatory:'));
+    } catch {
+      output.log('\nCancelled.');
+      return EXIT_CODES.SUCCESS;
+    }
+    if (!removeMandatory && selectedOptional.length === 0) {
+      output.log('No skills selected. Nothing uninstalled.');
+      return EXIT_CODES.SUCCESS;
+    }
+  }
+
+  const selected = [
+    ...(removeMandatory ? allMandatory : []),
+    ...selectedOptional,
+  ];
+  const removed = [];
+  for (const name of selected) {
+    let removedSomewhere = false;
+    for (const { dir, guard, identity } of existingTargetDirs) {
+      const destination = join(dir, name);
+      guard.assertPath(destination);
+      if (fs.existsSync(destination)) {
+        try {
+          guard.assertPath(destination);
+          const didRemove = withPinnedTargetDirectory(
+            dir,
+            identity,
+            fs,
+            () => removeSelectedEntry(name, fs),
+          );
+          guard.assertPath(dir);
+          removedSomewhere ||= didRemove;
+        } catch (error) {
+          throw new CliError(`Failed to uninstall '${name}'.`, 'REPOSITORY_CONFLICT', {
+            cause: error,
+          });
+        }
+      }
+    }
+    if (removedSomewhere) removed.push(name);
+  }
+
+  output.log(`Uninstalled ${removed.length} skills for: ${targets.join(', ')}`);
+  removed.forEach(name => output.log(`  -  ${name}`));
+  existingTargetDirs.forEach(({ target, displayDir }) => {
+    output.log(`  -> ${target}: ${displayDir}`);
+  });
+  await checkForUpdate(dependencies);
+  return EXIT_CODES.SUCCESS;
+}