tokrepo 3.5.0 → 3.7.0

package/bin/tokrepo.js

@@ -25,12 +25,13 @@ const CONFIG_DIR = path.join(os.homedir(), '.tokrepo');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const PROJECT_CONFIG = '.tokrepo.json';
 const DEFAULT_API = 'https://api.tokrepo.com';
-const CLI_VERSION = '3.5.0';
+const CLI_VERSION = '3.7.0';
 const VERSION_CHECK_FILE = path.join(os.homedir(), '.tokrepo', '.version-check');
 const CODEX_DIR = path.join(os.homedir(), '.codex');
 const CODEX_SKILLS_DIR = path.join(CODEX_DIR, 'skills');
 const CODEX_TOKREPO_DIR = path.join(CODEX_DIR, 'tokrepo');
 const CODEX_MANIFEST_FILE = path.join(CODEX_TOKREPO_DIR, 'install-manifest.json');
+const CODEX_SESSIONS_DIR = path.join(CODEX_TOKREPO_DIR, 'sessions');
 const SUPPORTED_INSTALL_TARGETS = ['gemini', 'codex'];
 
 // ─── Helpers ───
@@ -304,6 +305,7 @@ function parseArgs(argv) {
     'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'types',
     'kind', 'install-mode', 'install_mode', 'entrypoint', 'asset-kind', 'asset_kind',
     'version',
+    'policy', 'session',
     'page', 'page-size', 'page_size', 'sort-by', 'sort_by',
     'time-window', 'time_window',
   ]);
@@ -841,8 +843,23 @@ async function cmdSearch() {
       data = { ...data, list };
     }
 
+    const originalCount = (data.list || []).length;
+    data = { ...data, list: applyAgentWorkflowFilters(data.list || [], args.flags) };
+    const filters = {
+      target: args.flags.target || undefined,
+      kind: args.flags.kind || args.flags.assetKind || undefined,
+      policy: args.flags.policy || undefined,
+    };
+
     if (args.flags.json) {
-      outputJson({ query, total: data.total || 0, count: (data.list || []).length, list: data.list || [] });
+      outputJson({
+        query,
+        total: data.total || 0,
+        fetched: originalCount,
+        count: (data.list || []).length,
+        filters,
+        list: data.list || [],
+      });
       return;
     }
 
@@ -859,7 +876,8 @@ async function cmdSearch() {
       return;
     }
 
-    log(`  ${C.bold}${data.total}${C.reset} results:\n`);
+    const filterText = [filters.target ? `target=${filters.target}` : '', filters.kind ? `kind=${filters.kind}` : '', filters.policy ? `policy=${filters.policy}` : ''].filter(Boolean).join(' · ');
+    log(`  ${C.bold}${data.list.length}${C.reset} shown${filterText ? ` ${C.dim}(${filterText})${C.reset}` : ''}${data.total ? ` ${C.dim}from ${data.total} result(s)${C.reset}` : ''}:\n`);
 
     for (let i = 0; i < data.list.length; i++) {
       const wf = data.list[i];
@@ -874,6 +892,10 @@ async function cmdSearch() {
       log(`  ${C.dim}${String(i + 1).padStart(2)}.${C.reset} ${C.bold}${wf.title}${C.reset}`);
       if (desc) log(`      ${desc}`);
       if (tags) log(`      ${C.cyan}${tags}${C.reset}  ${C.dim}★${votes} 👁${views}${C.reset}`);
+      if (wf.compatibility?.codex) {
+        const c = wf.compatibility.codex;
+        log(`      ${C.dim}codex: ${c.status} · policy=${c.policyDecision.decision} · kind=${c.assetKind || 'unknown'}${C.reset}`);
+      }
       log(`      ${C.dim}tokrepo install ${wf.uuid}${C.reset}`);
       log('');
     }
@@ -984,6 +1006,40 @@ function getWorkflowAssetType(workflow) {
   return (workflow.tags[0].slug || workflow.tags[0].name || '').toLowerCase();
 }
 
+function workflowAgentMetadata(workflow) {
+  return workflow?.agent_metadata || workflow?.agentMetadata || {};
+}
+
+function normalizeCodexInstallMode(mode) {
+  const normalized = String(mode || '').trim().toLowerCase().replace(/-/g, '_');
+  return ['single', 'bundle', 'split', 'stage_only'].includes(normalized) ? normalized : '';
+}
+
+function workflowAssetKind(workflow) {
+  const metadata = workflowAgentMetadata(workflow);
+  const explicit = workflow?.asset_kind || workflow?.assetKind || metadata.asset_kind || metadata.assetKind || '';
+  if (explicit) return normalizeToolName(explicit);
+  const assetType = getWorkflowAssetType(workflow);
+  const aliases = {
+    skills: 'skill',
+    prompts: 'prompt',
+    knowledge: 'knowledge',
+    'mcp-configs': 'mcp_config',
+    mcp: 'mcp_config',
+    scripts: 'script',
+    configs: 'config',
+    tools: 'cli_tool',
+  };
+  return aliases[assetType] || normalizeToolName(assetType);
+}
+
+function workflowTargetTools(workflow) {
+  const metadata = workflowAgentMetadata(workflow);
+  return parseCsvList(workflow?.target_tools || workflow?.targetTools || metadata.target_tools || metadata.targetTools)
+    .map(normalizeToolName)
+    .filter(Boolean);
+}
+
 function extractInstallableContents(workflow, assetType) {
   const contents = [];
   const files = workflow.files || [];
@@ -1129,8 +1185,7 @@ function explicitInstallMode(workflow) {
     workflow?.metadata?.installMode,
     workflow?.metadata?.install_mode,
   ].filter(Boolean);
-  const mode = String(candidates[0] || '').toLowerCase();
-  return ['single', 'bundle', 'split', 'stage_only'].includes(mode) ? mode : '';
+  return normalizeCodexInstallMode(candidates[0]);
 }
 
 function inferCodexInstallMode(workflow, contents) {
@@ -1187,8 +1242,12 @@ function addPlanFile(plan, destPath, content, sourceName, type) {
 }
 
 function buildCodexInstallPlan(workflow, contents, opts = {}) {
-  const installMode = opts.installMode || inferCodexInstallMode(workflow, contents);
-  const agentMetadata = workflow?.agent_metadata || workflow?.agentMetadata || {};
+  const serverPlan = opts.serverPlan || null;
+  const serverMetadata = serverPlan?.metadata || serverPlan?.agentMetadata || serverPlan?.agent_metadata || {};
+  const installMode = normalizeCodexInstallMode(opts.installMode)
+    || normalizeCodexInstallMode(metadataValue(serverPlan, 'install_mode', 'installMode', ''))
+    || inferCodexInstallMode(workflow, contents);
+  const agentMetadata = Object.keys(serverMetadata || {}).length > 0 ? serverMetadata : workflowAgentMetadata(workflow);
   const plan = {
     uuid: workflow.uuid,
     title: workflow.title,
@@ -1199,7 +1258,8 @@ function buildCodexInstallPlan(workflow, contents, opts = {}) {
     files: [],
     risks: [],
     agentMetadata,
-    contentHash: workflow.content_hash || workflow.contentHash || agentMetadata.content_hash || '',
+    contentHash: workflow.content_hash || workflow.contentHash || agentMetadata.content_hash || agentMetadata.contentHash || metadataValue(serverPlan, 'content_hash', 'contentHash', ''),
+    serverPlan,
   };
 
   if (installMode === 'stage_only') {
@@ -1278,8 +1338,222 @@ function buildCodexInstallPlan(workflow, contents, opts = {}) {
   return plan;
 }
 
+function metadataValue(metadata, snakeName, camelName, fallback) {
+  if (!metadata) return fallback;
+  if (metadata[snakeName] !== undefined) return metadata[snakeName];
+  if (metadata[camelName] !== undefined) return metadata[camelName];
+  return fallback;
+}
+
+function normalizeToolName(value) {
+  return String(value || '').trim().toLowerCase().replace(/-/g, '_');
+}
+
+function riskProfileFromFlags(flags = []) {
+  const set = new Set(flags || []);
+  return {
+    executes_code: set.has('executable'),
+    modifies_global_config: set.has('mcp'),
+    requires_secrets: set.has('env') ? ['ENV'] : [],
+    uses_absolute_paths: set.has('absolute-path'),
+    network_access: set.has('network'),
+  };
+}
+
+function mergedPlanRiskProfile(plan) {
+  const metadata = plan.agentMetadata || {};
+  const rp = metadataValue(metadata, 'risk_profile', 'riskProfile', {}) || {};
+  const flags = new Set(plan.risks || []);
+  return {
+    executes_code: Boolean(rp.executes_code || rp.executesCode || flags.has('executable')),
+    modifies_global_config: Boolean(rp.modifies_global_config || rp.modifiesGlobalConfig || flags.has('mcp')),
+    requires_secrets: rp.requires_secrets || rp.requiresSecrets || (flags.has('env') ? ['ENV'] : []),
+    uses_absolute_paths: Boolean(rp.uses_absolute_paths || rp.usesAbsolutePaths || flags.has('absolute-path')),
+    network_access: Boolean(rp.network_access || rp.networkAccess || flags.has('network')),
+  };
+}
+
+function policyDecisionFromServerPlan(plan) {
+  const serverPlan = plan?.serverPlan;
+  if (!serverPlan) return null;
+  const raw = metadataValue(serverPlan, 'policy_decision', 'policyDecision', null);
+  if (!raw) return null;
+  if (typeof raw === 'string') {
+    return {
+      decision: raw,
+      requiresConfirmation: raw === 'confirm',
+      reasons: [],
+    };
+  }
+  const decision = String(raw.decision || raw.action || 'allow').trim().toLowerCase();
+  const requiresConfirmation = Boolean(
+    raw.requires_confirmation
+    || raw.requiresConfirmation
+    || metadataValue(serverPlan, 'requires_confirmation', 'requiresConfirmation', false)
+  );
+  const reasons = raw.reasons || raw.reason || [];
+  return {
+    decision,
+    requiresConfirmation,
+    reasons: Array.isArray(reasons) ? reasons : [String(reasons)].filter(Boolean),
+  };
+}
+
+function decideCodexPolicy(plan) {
+  const serverPolicy = policyDecisionFromServerPlan(plan);
+  if (serverPolicy) return serverPolicy;
+
+  const metadata = plan.agentMetadata || {};
+  const targetTools = metadataValue(metadata, 'target_tools', 'targetTools', []) || [];
+  const assetKind = normalizeToolName(metadataValue(metadata, 'asset_kind', 'assetKind', ''));
+  const risk = mergedPlanRiskProfile(plan);
+  let decision = 'allow';
+  const reasons = [];
+  const raise = (next) => {
+    const rank = { allow: 0, confirm: 1, stage_only: 2, deny: 3 };
+    if ((rank[next] || 0) > (rank[decision] || 0)) decision = next;
+  };
+
+  if (targetTools.length && !targetTools.map(normalizeToolName).includes('codex')) {
+    raise('confirm');
+    reasons.push('metadata target_tools does not include codex');
+  }
+  if (['script', 'cli_tool', 'mcp_config'].includes(assetKind)) {
+    raise('stage_only');
+    reasons.push(`asset_kind ${assetKind} is not activated directly for Codex`);
+  }
+  if (plan.installMode === 'stage_only') {
+    raise('stage_only');
+    reasons.push('install_mode is stage_only');
+  }
+  if (risk.executes_code) {
+    raise('stage_only');
+    reasons.push('risk_profile.executes_code is true');
+  }
+  if (risk.modifies_global_config) {
+    raise('stage_only');
+    reasons.push('risk_profile.modifies_global_config is true');
+  }
+  if ((risk.requires_secrets || []).length) {
+    raise('stage_only');
+    reasons.push('risk_profile.requires_secrets is not empty');
+  }
+  if (risk.uses_absolute_paths) {
+    raise('confirm');
+    reasons.push('risk_profile.uses_absolute_paths is true');
+  }
+  if (risk.network_access) {
+    raise('confirm');
+    reasons.push('risk_profile.network_access is true');
+  }
+  if (reasons.length === 0) reasons.push('safe markdown-only Codex install');
+
+  return {
+    decision,
+    requiresConfirmation: decision === 'confirm',
+    reasons: Array.from(new Set(reasons)),
+  };
+}
+
+function buildPublicPlanActions(plan) {
+  const serverActions = metadataValue(plan.serverPlan, 'actions', 'actions', null);
+  if (serverConcretePlanMatchesLocal(plan) && Array.isArray(serverActions) && serverActions.length > 0) return serverActions;
+
+  const stage = plan.installMode === 'stage_only';
+  return plan.files.map(file => ({
+    type: stage ? 'stage_file' : 'write_file',
+    path: file.path,
+    sourceName: file.sourceName,
+    sha256: file.sha256,
+    bytes: file.bytes,
+    ifExists: 'overwrite',
+    entrypoint: path.basename(file.path).toLowerCase() === 'skill.md',
+    risk: riskProfileFromFlags(file.riskFlags || []),
+  }));
+}
+
+function serverConcretePlanMatchesLocal(plan) {
+  const serverActions = metadataValue(plan.serverPlan, 'actions', 'actions', null);
+  if (!Array.isArray(serverActions) || serverActions.length !== (plan.files || []).length) return false;
+  return serverActions.every((action, index) => {
+    const file = plan.files[index];
+    if (!file) return false;
+    const serverPath = path.resolve(expandHomePath(action.path || ''));
+    const localPath = path.resolve(file.path || '');
+    const serverSha = action.sha256 || action.sha || '';
+    return serverPath === localPath && (!serverSha || serverSha === file.sha256);
+  });
+}
+
+function buildPublicPlanPreconditions(plan, policyDecision) {
+  const serverPreconditions = metadataValue(plan.serverPlan, 'preconditions', 'preconditions', null);
+  if (Array.isArray(serverPreconditions) && serverPreconditions.length > 0) return serverPreconditions;
+
+  const metadata = plan.agentMetadata || {};
+  const targetTools = metadataValue(metadata, 'target_tools', 'targetTools', []) || [];
+  const out = [
+    { type: 'target_supported', status: 'pass', message: 'codex install target is supported' },
+    { type: 'install_root', status: 'pass', message: '~/.codex/skills for activated skills; ~/.codex/tokrepo/staged for staged assets' },
+  ];
+  if (!targetTools.length || targetTools.map(normalizeToolName).includes('codex')) {
+    out.push({ type: 'target_tool_metadata', status: 'pass', message: 'metadata allows codex' });
+  } else {
+    out.push({ type: 'target_tool_metadata', status: 'warn', message: 'metadata target_tools does not include codex' });
+  }
+  out.push({
+    type: 'content_hash',
+    status: plan.contentHash ? 'pass' : 'warn',
+    message: plan.contentHash ? 'asset metadata includes content_hash' : 'asset metadata does not include content_hash',
+  });
+  const policyStatus = policyDecision.decision === 'deny' ? 'block'
+    : policyDecision.decision === 'allow' ? 'pass'
+    : 'warn';
+  out.push({ type: 'policy_decision', status: policyStatus, message: `${policyDecision.decision} for ${plan.uuid}` });
+  return out;
+}
+
+function buildPublicPlanRollback(plan) {
+  const serverRollback = metadataValue(plan.serverPlan, 'rollback', 'rollback', null);
+  if (serverConcretePlanMatchesLocal(plan) && Array.isArray(serverRollback) && serverRollback.length > 0) return serverRollback;
+
+  const seen = new Set();
+  const rollback = [];
+  for (const file of plan.files) {
+    if (!file.path || seen.has(file.path)) continue;
+    seen.add(file.path);
+    rollback.push({ type: 'remove_file', path: file.path });
+  }
+  return rollback;
+}
+
+function buildPublicPlanPostVerify(plan) {
+  const serverPostVerify = metadataValue(plan.serverPlan, 'post_verify', 'postVerify', null);
+  if (serverConcretePlanMatchesLocal(plan) && Array.isArray(serverPostVerify) && serverPostVerify.length > 0) return serverPostVerify;
+
+  const metadata = plan.agentMetadata || {};
+  const verification = metadataValue(metadata, 'verification', 'verification', {}) || {};
+  const out = plan.files.map(file => ({ type: 'file_sha256', path: file.path, sha256: file.sha256 }));
+  const installedPaths = new Set(plan.files.map(file => path.resolve(file.path)));
+  for (const expected of (verification.expected_files || verification.expectedFiles || [])) {
+    const resolvedExpected = path.resolve(resolveVerifyPath(expected, { baseDir: plan.baseDir, files: plan.files }));
+    if (installedPaths.has(resolvedExpected)) {
+      out.push({ type: 'expected_file', path: expected });
+    }
+  }
+  for (const command of (verification.commands || [])) {
+    out.push({ type: 'command', command });
+  }
+  return out;
+}
+
 function publicInstallPlan(plan) {
+  const policyDecision = decideCodexPolicy(plan);
+  const actions = buildPublicPlanActions(plan);
+  const schemaVersion = Number(metadataValue(plan.serverPlan, 'schema_version', 'schemaVersion', 2)) || 2;
   return {
+    schemaVersion,
+    sourceOfTruth: plan.serverPlan ? 'api_install_plan_v2' : 'local_fallback',
+    concretePlanSource: serverConcretePlanMatchesLocal(plan) ? 'api_install_plan_v2' : 'local_fallback',
     uuid: plan.uuid,
     title: plan.title,
     sourceUrl: plan.sourceUrl,
@@ -1288,7 +1562,12 @@ function publicInstallPlan(plan) {
     manifestPath: plan.manifestPath,
     baseDir: plan.baseDir,
     risks: plan.risks,
-    requiresConfirmation: hasCodexInstallRisks(plan),
+    preconditions: buildPublicPlanPreconditions(plan, policyDecision),
+    actions,
+    policyDecision,
+    requiresConfirmation: policyDecision.requiresConfirmation,
+    rollback: buildPublicPlanRollback(plan),
+    postVerify: buildPublicPlanPostVerify(plan),
     contentHash: plan.contentHash || '',
     agentMetadata: plan.agentMetadata || {},
     files: plan.files.map(file => ({
@@ -1302,8 +1581,98 @@ function publicInstallPlan(plan) {
   };
 }
 
+function workflowCodexCompatibility(workflow) {
+  const metadata = workflowAgentMetadata(workflow);
+  const assetKind = workflowAssetKind(workflow);
+  const targetTools = workflowTargetTools(workflow);
+  const installMode = normalizeCodexInstallMode(metadata.install_mode || metadata.installMode || workflow.install_mode || workflow.installMode) || 'single';
+  const policy = decideCodexPolicy({
+    agentMetadata: {
+      ...metadata,
+      asset_kind: assetKind,
+      target_tools: targetTools,
+      install_mode: installMode,
+    },
+    risks: [],
+    installMode,
+  });
+  const scores = { allow: 100, confirm: 70, stage_only: 40, deny: 0 };
+  const statuses = {
+    allow: 'native',
+    confirm: 'requires_confirmation',
+    stage_only: 'stage_only',
+    deny: 'denied',
+  };
+  return {
+    targetTool: 'codex',
+    status: statuses[policy.decision] || 'unknown',
+    score: scores[policy.decision] ?? 50,
+    assetKind,
+    targetTools,
+    installMode,
+    policyDecision: policy,
+  };
+}
+
+function workflowMatchesAgentFilters(workflow, flags = {}) {
+  const target = normalizeInstallTarget(flags.target || '');
+  const requestedKinds = parseCsvList(flags.kind || flags.assetKind || flags.asset_kind).map(normalizeToolName);
+  const requestedPolicies = parseCsvList(flags.policy).map(s => String(s).trim().toLowerCase());
+  const assetKind = workflowAssetKind(workflow);
+  const targetTools = workflowTargetTools(workflow);
+  const compatibility = workflowCodexCompatibility(workflow);
+
+  if (target === 'codex') {
+    if (targetTools.length > 0 && !targetTools.includes('codex')) return false;
+  } else if (target && targetTools.length > 0 && !targetTools.includes(target)) {
+    return false;
+  }
+
+  if (requestedKinds.length > 0) {
+    const kindAliases = new Set([assetKind, `${assetKind}s`, assetKind.replace(/_/g, '-')]);
+    const tags = (workflow.tags || []).flatMap(t => [t.slug, t.name]).filter(Boolean).map(normalizeToolName);
+    const matchesKind = requestedKinds.some(kind => kindAliases.has(kind) || tags.includes(kind) || tags.includes(`${kind}s`));
+    if (!matchesKind) return false;
+  }
+
+  if (requestedPolicies.length > 0) {
+    const decision = compatibility.policyDecision.decision;
+    const aliases = {
+      safe: 'allow',
+      staged: 'stage_only',
+      stage: 'stage_only',
+      block: 'deny',
+      blocked: 'deny',
+    };
+    const normalizedPolicies = requestedPolicies.map(policy => aliases[policy] || policy);
+    if (!normalizedPolicies.includes(decision)) return false;
+  }
+
+  return true;
+}
+
+function enrichWorkflowForAgent(workflow) {
+  const compatibility = workflowCodexCompatibility(workflow);
+  return {
+    ...workflow,
+    assetKind: compatibility.assetKind,
+    targetTools: compatibility.targetTools,
+    compatibility: {
+      codex: compatibility,
+    },
+    policyDecision: compatibility.policyDecision,
+  };
+}
+
+function applyAgentWorkflowFilters(list, flags = {}) {
+  const shouldEnrich = flags.target || flags.kind || flags.assetKind || flags.asset_kind || flags.policy;
+  const filtered = (list || []).filter(item => workflowMatchesAgentFilters(item, flags));
+  return shouldEnrich ? filtered.map(enrichWorkflowForAgent) : filtered;
+}
+
 function hasCodexInstallRisks(plan) {
-  return (plan.risks || []).some(risk => ['mcp', 'executable', 'env', 'absolute-path'].includes(risk));
+  const decision = decideCodexPolicy(plan).decision;
+  return decision === 'confirm' || decision === 'stage_only' || decision === 'deny';
 }
 
 function formatRiskLine(file) {
@@ -1312,15 +1681,19 @@ function formatRiskLine(file) {
 }
 
 async function confirmCodexInstallRisks(plan, opts = {}) {
+  const policy = decideCodexPolicy(plan);
+  if (policy.decision === 'deny') {
+    throw new Error(`Install policy denied this asset: ${policy.reasons.join('; ')}`);
+  }
   if (plan.installMode === 'stage_only') return;
-  if (opts.dryRun || opts.stage || !hasCodexInstallRisks(plan)) return;
+  if (opts.dryRun || opts.stage || policy.decision === 'allow') return;
   if (opts.approveMcp || opts.approve_mcp || opts.yes) return;
 
   if (opts.json || opts.throwOnError || process.env.TOKREPO_NONINTERACTIVE === '1') {
-    throw new Error(`Install plan includes risky content (${plan.risks.join(', ')}). Re-run with --dry-run to inspect or --approve-mcp to approve writing the Codex skill bundle.`);
+    throw new Error(`Install policy is ${policy.decision}: ${policy.reasons.join('; ')}. Re-run with --dry-run to inspect, --stage to stage the plan, or --approve-mcp to approve writing the Codex skill bundle.`);
   }
 
-  warn(`This asset contains ${plan.risks.join(', ')} content.`);
+  warn(`Install policy is ${policy.decision}: ${policy.reasons.join('; ')}`);
   log(`  ${C.dim}TokRepo will only write files under ${CODEX_SKILLS_DIR}; it will not merge MCP configs, modify PATH, or execute scripts.${C.reset}`);
   const riskyFiles = plan.files
     .map(formatRiskLine)
@@ -1375,6 +1748,102 @@ function executeStageOnlyCodexPlan(plan) {
   return { dryRun: true, staged: true, stageOnly: true, stagePath, plan: publicInstallPlan(plan), installedFiles };
 }
 
+function expandHomePath(input) {
+  const value = String(input || '');
+  if (value === '~') return os.homedir();
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolveVerifyPath(checkPath, publicPlan) {
+  const expanded = expandHomePath(checkPath);
+  if (path.isAbsolute(expanded)) return expanded;
+  const baseDir = publicPlan.baseDir || path.dirname(publicPlan.files?.[0]?.path || CODEX_SKILLS_DIR);
+  return path.join(baseDir, expanded);
+}
+
+function runCodexPostVerify(publicPlan, opts = {}) {
+  const checks = [];
+  let ok = true;
+  for (const check of (publicPlan.postVerify || [])) {
+    if (check.type === 'file_sha256') {
+      const filePath = resolveVerifyPath(check.path, publicPlan);
+      const exists = fs.existsSync(filePath);
+      const actualSha = exists ? currentFileSha(filePath) : '';
+      const passed = Boolean(exists && actualSha === check.sha256);
+      if (!passed) ok = false;
+      checks.push({ ...check, path: filePath, status: passed ? 'pass' : 'fail', actualSha });
+    } else if (check.type === 'expected_file') {
+      const filePath = resolveVerifyPath(check.path, publicPlan);
+      const passed = fs.existsSync(filePath);
+      if (!passed) ok = false;
+      checks.push({ ...check, path: filePath, status: passed ? 'pass' : 'fail' });
+    } else if (check.type === 'command') {
+      if (!opts.verifyCommands) {
+        checks.push({ ...check, status: 'skipped', message: 'command verification is opt-in; re-run with --verify-commands' });
+        continue;
+      }
+      try {
+        const childProcess = require('child_process');
+        childProcess.execSync(String(check.command || ''), { stdio: 'pipe', shell: true, timeout: 30000 });
+        checks.push({ ...check, status: 'pass' });
+      } catch (e) {
+        ok = false;
+        checks.push({ ...check, status: 'fail', message: e.message });
+      }
+    } else {
+      checks.push({ ...check, status: 'skipped', message: 'unknown verification check type' });
+    }
+  }
+  return { ok, checks };
+}
+
+function createCodexSessionId(operation = 'session') {
+  const stamp = new Date().toISOString().replace(/[-:.]/g, '').replace('T', '-').replace('Z', '');
+  const random = crypto.randomBytes(4).toString('hex');
+  return `${slugify(operation, 'session')}-${stamp}-${random}`;
+}
+
+function writeCodexSession(record) {
+  if (!fs.existsSync(CODEX_SESSIONS_DIR)) {
+    fs.mkdirSync(CODEX_SESSIONS_DIR, { recursive: true, mode: 0o700 });
+  }
+  const sessionId = record.sessionId || createCodexSessionId(record.operation || 'session');
+  const sessionPath = path.join(CODEX_SESSIONS_DIR, `${sessionId}.json`);
+  const payload = {
+    schemaVersion: 1,
+    sessionId,
+    createdAt: new Date().toISOString(),
+    cliVersion: CLI_VERSION,
+    argv: process.argv.slice(2),
+    ...record,
+    sessionId,
+  };
+  fs.writeFileSync(sessionPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  return { sessionId, sessionPath };
+}
+
+function readCodexSessions() {
+  try {
+    if (!fs.existsSync(CODEX_SESSIONS_DIR)) return [];
+    return fs.readdirSync(CODEX_SESSIONS_DIR)
+      .filter(name => name.endsWith('.json'))
+      .map(name => {
+        const sessionPath = path.join(CODEX_SESSIONS_DIR, name);
+        try {
+          const parsed = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+          return { ...parsed, sessionPath };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+  } catch {
+    return [];
+  }
+}
+
 function readCodexManifest() {
   try {
     const parsed = JSON.parse(fs.readFileSync(CODEX_MANIFEST_FILE, 'utf8'));
@@ -1383,7 +1852,15 @@ function readCodexManifest() {
   return { schemaVersion: 1, installs: [] };
 }
 
-function writeCodexManifestRecord(plan, installedFiles) {
+function writeCodexManifest(manifest) {
+  if (!fs.existsSync(CODEX_TOKREPO_DIR)) {
+    fs.mkdirSync(CODEX_TOKREPO_DIR, { recursive: true, mode: 0o700 });
+  }
+  manifest.updatedAt = new Date().toISOString();
+  fs.writeFileSync(CODEX_MANIFEST_FILE, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+}
+
+function writeCodexManifestRecord(plan, installedFiles, sessionInfo = {}, verification = null) {
   if (!fs.existsSync(CODEX_TOKREPO_DIR)) {
     fs.mkdirSync(CODEX_TOKREPO_DIR, { recursive: true, mode: 0o700 });
   }
@@ -1398,6 +1875,9 @@ function writeCodexManifestRecord(plan, installedFiles) {
     installedAt,
     contentHash: plan.contentHash || '',
     agentMetadata: plan.agentMetadata || {},
+    sessionId: sessionInfo.sessionId,
+    sessionPath: sessionInfo.sessionPath,
+    verification,
     installedFiles: installedFiles.map(file => ({
       path: file.path,
       sourceName: file.sourceName,
@@ -1410,16 +1890,58 @@ function writeCodexManifestRecord(plan, installedFiles) {
   manifest.installs = manifest.installs.filter(item => !(item.uuid === plan.uuid && item.targetTool === 'codex'));
   manifest.installs.push(record);
   manifest.updatedAt = installedAt;
-  fs.writeFileSync(CODEX_MANIFEST_FILE, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  writeCodexManifest(manifest);
   return record;
 }
 
 function executeCodexInstallPlan(plan, opts = {}) {
-  if (opts.dryRun) return { dryRun: true, plan: publicInstallPlan(plan), installedFiles: [] };
-  if (plan.installMode === 'stage_only') return executeStageOnlyCodexPlan(plan);
+  const publicPlan = publicInstallPlan(plan);
+  if (opts.dryRun) {
+    const session = writeCodexSession({
+      operation: 'install',
+      status: 'dry_run',
+      targetTool: 'codex',
+      uuid: plan.uuid,
+      title: plan.title,
+      sourceUrl: plan.sourceUrl,
+      policyDecision: publicPlan.policyDecision,
+      plan: publicPlan,
+      result: { dryRun: true, installedFiles: [] },
+    });
+    return { dryRun: true, plan: publicPlan, installedFiles: [], ...session };
+  }
+  if (plan.installMode === 'stage_only') {
+    const result = executeStageOnlyCodexPlan(plan);
+    const verification = runCodexPostVerify(result.plan, opts);
+    const session = writeCodexSession({
+      operation: 'install',
+      status: 'stage_only',
+      targetTool: 'codex',
+      uuid: plan.uuid,
+      title: plan.title,
+      sourceUrl: plan.sourceUrl,
+      policyDecision: result.plan.policyDecision,
+      plan: result.plan,
+      installedFiles: result.installedFiles,
+      verification,
+      result: { staged: true, stageOnly: true, stagePath: result.stagePath },
+    });
+    return { ...result, verification, ...session };
+  }
   if (opts.stage) {
     const stagePath = stageCodexInstallPlan(plan);
-    return { dryRun: true, staged: true, stagePath, plan: publicInstallPlan(plan), installedFiles: [] };
+    const session = writeCodexSession({
+      operation: 'install',
+      status: 'staged',
+      targetTool: 'codex',
+      uuid: plan.uuid,
+      title: plan.title,
+      sourceUrl: plan.sourceUrl,
+      policyDecision: publicPlan.policyDecision,
+      plan: publicPlan,
+      result: { staged: true, stagePath },
+    });
+    return { dryRun: true, staged: true, stagePath, plan: publicPlan, installedFiles: [], ...session };
   }
 
   const installedFiles = [];
@@ -1439,8 +1961,22 @@ function executeCodexInstallPlan(plan, opts = {}) {
     });
   }
 
-  const manifestRecord = writeCodexManifestRecord(plan, installedFiles);
-  return { dryRun: false, plan: publicInstallPlan(plan), installedFiles, manifestRecord };
+  const verification = runCodexPostVerify(publicPlan, opts);
+  const session = writeCodexSession({
+    operation: 'install',
+    status: 'installed',
+    targetTool: 'codex',
+    uuid: plan.uuid,
+    title: plan.title,
+    sourceUrl: plan.sourceUrl,
+    policyDecision: publicPlan.policyDecision,
+    plan: publicPlan,
+    installedFiles,
+    verification,
+    result: { installedFiles },
+  });
+  const manifestRecord = writeCodexManifestRecord(plan, installedFiles, session, verification);
+  return { dryRun: false, plan: publicPlan, installedFiles, manifestRecord, verification, ...session };
 }
 
 async function installCodexAsset(workflow, contents, opts = {}) {
@@ -1468,6 +2004,7 @@ async function cmdInstall() {
     dryRun: Boolean(args.flags.dryRun || args.flags.dry_run),
     stage: Boolean(args.flags.stage),
     approveMcp: Boolean(args.flags.approveMcp || args.flags.approve_mcp),
+    verifyCommands: Boolean(args.flags.verify_commands || args.flags.verifyCommands),
     json: Boolean(args.flags.json),
     manifest: Boolean(args.flags.manifest),
   };
@@ -1488,6 +2025,33 @@ async function cmdInstall() {
   }
 }
 
+async function cmdPlan() {
+  const args = parseArgs(process.argv);
+  const target = args.positional[0];
+  if (!target) {
+    showPlanHelp();
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') {
+    error(`plan currently supports --target codex only`);
+  }
+  const result = await installOneAsset(target, config, apiBase, {
+    targetTool,
+    dryRun: true,
+    stage: Boolean(args.flags.stage),
+    installMode: args.flags.installMode,
+    json: true,
+    manifest: true,
+    throwOnError: true,
+  });
+
+  outputJson(result.plan);
+}
+
 // Install all assets in a theme pack — sequentially, continue past per-item errors
 async function installPack(slug, config, apiBase, opts) {
   info(`Fetching pack ${C.bold}${slug}${C.reset}...`);
@@ -1617,7 +2181,8 @@ async function installOneAsset(target, config, apiBase, opts) {
   if (targetTool === 'codex') {
     let result;
     try {
-      result = await installCodexAsset(workflow, contents, opts);
+      const serverPlan = opts.serverPlan !== undefined ? opts.serverPlan : await fetchServerCodexInstallPlan(uuid, config, apiBase);
+      result = await installCodexAsset(workflow, contents, { ...opts, serverPlan });
     } catch (e) {
       die(e.message);
     }
@@ -1631,6 +2196,7 @@ async function installOneAsset(target, config, apiBase, opts) {
         } else {
           info(`No Codex skill files were written. Re-run with --approve-mcp or --yes to install.`);
         }
+        if (result.sessionPath) log(`  ${C.dim}Session: ${result.sessionPath}${C.reset}`);
       } else if (opts.dryRun) {
         info(`Dry run: ${plan.files.length} file(s) would be installed to ${CODEX_SKILLS_DIR}`);
         for (const file of plan.files) {
@@ -1638,6 +2204,7 @@ async function installOneAsset(target, config, apiBase, opts) {
           log(`  ${C.dim}•${C.reset} ~/${rel}`);
           if (file.riskFlags.length) log(`    ${C.yellow}${file.riskFlags.join(', ')}${C.reset}`);
         }
+        if (result.sessionPath) log(`  ${C.dim}Session: ${result.sessionPath}${C.reset}`);
       } else {
         for (const file of result.installedFiles) {
           const relPath = path.relative(os.homedir(), file.path);
@@ -1646,6 +2213,8 @@ async function installOneAsset(target, config, apiBase, opts) {
         log('');
         success(`${result.installedFiles.length} file(s) installed from ${C.bold}${workflow.title}${C.reset}`);
         log(`  ${C.dim}Manifest: ${CODEX_MANIFEST_FILE}${C.reset}`);
+        if (result.sessionPath) log(`  ${C.dim}Session: ${result.sessionPath}${C.reset}`);
+        if (result.verification && !result.verification.ok) log(`  ${C.yellow}Verification: failed${C.reset}`);
         log(`  ${C.dim}Source: https://tokrepo.com/en/workflows/${uuid}${C.reset}\n`);
       }
     }
@@ -1661,6 +2230,9 @@ async function installOneAsset(target, config, apiBase, opts) {
       installedFiles: result.installedFiles || [],
       plan: result.plan,
       manifestPath: CODEX_MANIFEST_FILE,
+      sessionId: result.sessionId,
+      sessionPath: result.sessionPath,
+      verification: result.verification,
     };
   }
 
@@ -1822,8 +2394,16 @@ async function cmdList() {
       data = { ...data, list };
     }
 
+    const originalCount = (data.list || []).length;
+    data = { ...data, list: applyAgentWorkflowFilters(data.list || [], args.flags) };
+    const filters = {
+      target: args.flags.target || undefined,
+      kind: args.flags.kind || args.flags.assetKind || undefined,
+      policy: args.flags.policy || undefined,
+    };
+
     if (args.flags.json) {
-      outputJson({ total: data.total || 0, count: (data.list || []).length, list: data.list || [] });
+      outputJson({ total: data.total || 0, fetched: originalCount, count: (data.list || []).length, filters, list: data.list || [] });
       return;
     }
 
@@ -1832,11 +2412,16 @@ async function cmdList() {
       return;
     }
 
-    log(`  ${C.bold}${data.total}${C.reset} assets:\n`);
+    const filterText = [filters.target ? `target=${filters.target}` : '', filters.kind ? `kind=${filters.kind}` : '', filters.policy ? `policy=${filters.policy}` : ''].filter(Boolean).join(' · ');
+    log(`  ${C.bold}${data.list.length}${C.reset} assets${filterText ? ` ${C.dim}(${filterText})${C.reset}` : ''}${data.total ? ` ${C.dim}from ${data.total}${C.reset}` : ''}:\n`);
 
     for (const wf of data.list) {
       const views = wf.view_count || 0;
       log(`  ${C.cyan}${wf.uuid.substring(0,8)}${C.reset}  ${C.bold}${wf.title}${C.reset}`);
+      if (wf.compatibility?.codex) {
+        const c = wf.compatibility.codex;
+        log(`  ${C.dim}         codex=${c.status} · policy=${c.policyDecision.decision} · kind=${c.assetKind || 'unknown'}${C.reset}`);
+      }
       log(`  ${C.dim}         ${views} views · https://tokrepo.com/en/workflows/${wf.uuid}${C.reset}\n`);
     }
   } catch (e) {
@@ -2046,13 +2631,16 @@ async function cmdClone() {
           const assetType = getWorkflowAssetType(workflow);
           const contents = extractInstallableContents(workflow, assetType);
           if (contents.length === 0) throw new Error('No installable content found');
+          const serverPlan = await fetchServerCodexInstallPlan(workflow.uuid, config, apiBase);
           const result = await installCodexAsset(workflow, contents, {
             ...args.flags,
             dryRun,
             stage: Boolean(args.flags.stage),
             approveMcp: Boolean(args.flags.approveMcp || args.flags.approve_mcp),
+            verifyCommands: Boolean(args.flags.verify_commands || args.flags.verifyCommands),
             json: true,
             throwOnError: true,
+            serverPlan,
           });
           if (!dryRun) installedCount += result.installedFiles.length;
           results.push({
@@ -2065,6 +2653,9 @@ async function cmdClone() {
             files: result.plan.files,
             installedFiles: result.installedFiles || [],
             risks: result.plan.risks,
+            sessionId: result.sessionId,
+            sessionPath: result.sessionPath,
+            verification: result.verification,
           });
           if (!json) {
             const fileCount = (dryRun || args.flags.stage) ? result.plan.files.length : result.installedFiles.length;
@@ -2193,6 +2784,15 @@ async function fetchWorkflowForInstall(uuid, config, apiBase) {
   return { workflow, contents };
 }
 
+async function fetchServerCodexInstallPlan(uuid, config, apiBase) {
+  try {
+    const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/install-plan?uuid=${encodeURIComponent(uuid)}&target=codex`, null, config?.token, apiBase);
+    return data?.plan || data || null;
+  } catch {
+    return null;
+  }
+}
+
 async function cmdSyncInstalled() {
   const args = parseArgs(process.argv);
   const targetTool = validateInstallTarget(args.flags.target || 'codex');
@@ -2227,7 +2827,8 @@ async function cmdSyncInstalled() {
 
     try {
       const { workflow, contents } = await fetchWorkflowForInstall(uuid, config, apiBase);
-      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode });
+      const serverPlan = await fetchServerCodexInstallPlan(uuid, config, apiBase);
+      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode, serverPlan });
       const diff = diffCodexPlanWithLocal(plan, record);
       const shouldWrite = force || diff.needsUpdate;
 
@@ -2265,8 +2866,10 @@ async function cmdSyncInstalled() {
         stage,
         installMode: record.installMode || record.install_mode,
         approveMcp: Boolean(args.flags.approveMcp || args.flags.approve_mcp),
+        verifyCommands: Boolean(args.flags.verify_commands || args.flags.verifyCommands),
         json: true,
         throwOnError: true,
+        serverPlan,
       });
 
       results.push({
@@ -2278,6 +2881,9 @@ async function cmdSyncInstalled() {
         stagePath: installResult.stagePath,
         installedFiles: installResult.installedFiles || [],
         plan: installResult.plan,
+        sessionId: installResult.sessionId,
+        sessionPath: installResult.sessionPath,
+        verification: installResult.verification,
       });
       if (!json) success(stage ? `Staged ${installResult.plan.files.length} file(s)` : `Updated ${(installResult.installedFiles || []).length} file(s)`);
     } catch (e) {
@@ -2336,6 +2942,8 @@ async function cmdInstalled() {
       installMode: record.installMode || record.install_mode,
       installedAt: record.installedAt || record.installed_at,
       contentHash: record.contentHash || record.content_hash || '',
+      sessionId: record.sessionId || record.session_id,
+      sessionPath: record.sessionPath || record.session_path,
       risks: record.risks || [],
       files,
       status: files.some(file => !file.exists) ? 'missing-files' : files.some(file => file.changed) ? 'local-changes' : 'installed',
@@ -2359,6 +2967,281 @@ async function cmdInstalled() {
   }
 }
 
+function isCodexManagedPath(filePath) {
+  const resolved = path.resolve(expandHomePath(filePath));
+  return ensureInside(CODEX_SKILLS_DIR, resolved) || ensureInside(path.join(CODEX_TOKREPO_DIR, 'staged'), resolved);
+}
+
+function removeEmptyCodexDirs(startDir) {
+  const roots = [CODEX_SKILLS_DIR, path.join(CODEX_TOKREPO_DIR, 'staged')].map(root => path.resolve(root));
+  let dir = path.resolve(startDir);
+  const root = roots.find(candidate => dir === candidate || dir.startsWith(candidate + path.sep));
+  if (!root) return;
+  while (dir !== root && dir.startsWith(root + path.sep)) {
+    try {
+      if (!fs.existsSync(dir) || fs.readdirSync(dir).length > 0) break;
+      fs.rmdirSync(dir);
+    } catch {
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+}
+
+function findCodexManifestRecord(selector) {
+  const manifest = readCodexManifest();
+  const records = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  const needle = String(selector || '').trim();
+  if (!needle) return null;
+  const lower = needle.toLowerCase();
+  const exact = records.find(record => String(record.uuid || '').toLowerCase() === lower);
+  if (exact) return exact;
+
+  const prefixMatches = /^[a-f0-9-]{8,}$/i.test(needle)
+    ? records.filter(record => String(record.uuid || '').toLowerCase().startsWith(lower))
+    : [];
+  if (prefixMatches.length === 1) return prefixMatches[0];
+  if (prefixMatches.length > 1) throw new Error(`Multiple installed assets match "${selector}". Use the full UUID.`);
+
+  const slugNeedle = slugify(needle, '');
+  const titleMatches = records.filter(record => {
+    const title = String(record.title || '').toLowerCase();
+    const sourceUrl = String(record.sourceUrl || record.source_url || '').toLowerCase();
+    return title === lower || slugify(record.title || '', '') === slugNeedle || sourceUrl.includes(lower);
+  });
+  if (titleMatches.length === 1) return titleMatches[0];
+  if (titleMatches.length > 1) throw new Error(`Multiple installed assets match "${selector}". Use the UUID.`);
+
+  const fuzzy = records.filter(record => String(record.title || '').toLowerCase().includes(lower));
+  if (fuzzy.length === 1) return fuzzy[0];
+  if (fuzzy.length > 1) throw new Error(`Multiple installed assets match "${selector}". Use the UUID.`);
+  return null;
+}
+
+function buildCodexRemovalPlan(record, files, opts = {}) {
+  const actions = (files || []).map(file => {
+    const filePath = path.resolve(expandHomePath(file.path));
+    const exists = fs.existsSync(filePath);
+    const actualSha = exists ? currentFileSha(filePath) : '';
+    const expectedSha = file.sha256 || '';
+    const changed = Boolean(exists && expectedSha && actualSha !== expectedSha);
+    const managed = isCodexManagedPath(filePath);
+    const allowed = managed && (!changed || opts.force);
+    const reason = !managed ? 'outside-managed-roots'
+      : changed && !opts.force ? 'local-changes'
+      : exists ? 'remove'
+      : 'already-missing';
+    return {
+      type: 'remove_file',
+      path: filePath,
+      sourceName: file.sourceName || file.source_name,
+      expectedSha,
+      actualSha,
+      exists,
+      changed,
+      allowed,
+      reason,
+    };
+  });
+  return {
+    schemaVersion: 1,
+    operation: opts.operation || 'uninstall',
+    targetTool: 'codex',
+    uuid: record.uuid,
+    title: record.title,
+    sourceUrl: record.sourceUrl || record.source_url,
+    manifestPath: CODEX_MANIFEST_FILE,
+    force: Boolean(opts.force),
+    dryRun: Boolean(opts.dryRun),
+    requiresConfirmation: actions.some(action => !action.allowed),
+    actions,
+  };
+}
+
+function executeCodexRemovalPlan(plan, opts = {}) {
+  const blocked = plan.actions.filter(action => !action.allowed);
+  if (blocked.length > 0) {
+    const first = blocked[0];
+    throw new Error(`Refusing to remove ${first.path}: ${first.reason}. Use --force only if you want to remove local changes.`);
+  }
+
+  const removedFiles = [];
+  const skippedFiles = [];
+  for (const action of plan.actions) {
+    if (!action.exists) {
+      skippedFiles.push({ path: action.path, reason: 'already-missing' });
+      continue;
+    }
+    fs.unlinkSync(action.path);
+    removedFiles.push({ path: action.path, sha256: action.actualSha || action.expectedSha });
+    removeEmptyCodexDirs(path.dirname(action.path));
+  }
+
+  const session = writeCodexSession({
+    operation: plan.operation,
+    status: plan.operation === 'rollback' ? 'rolled_back' : 'uninstalled',
+    targetTool: 'codex',
+    uuid: plan.uuid,
+    title: plan.title,
+    sourceUrl: plan.sourceUrl,
+    plan,
+    result: { removedFiles, skippedFiles },
+  });
+
+  if (opts.removeManifest !== false && plan.uuid) {
+    const manifest = readCodexManifest();
+    manifest.installs = (manifest.installs || []).filter(item => !((item.targetTool || item.target_tool) === 'codex' && item.uuid === plan.uuid));
+    writeCodexManifest(manifest);
+  }
+
+  return { dryRun: false, plan, removedFiles, skippedFiles, ...session };
+}
+
+async function cmdUninstall() {
+  const args = parseArgs(process.argv);
+  const target = args.positional[0];
+  if (!target) {
+    showUninstallHelp();
+    process.exit(1);
+  }
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') error(`uninstall currently supports --target codex only`);
+
+  const json = Boolean(args.flags.json);
+  const dryRun = Boolean(args.flags.dryRun || args.flags.dry_run);
+  const force = Boolean(args.flags.force);
+  if (!json) log(`\n${C.bold}tokrepo uninstall${C.reset}\n`);
+
+  try {
+    const record = findCodexManifestRecord(target);
+    if (!record) error(`No installed Codex asset found for "${target}". Run: tokrepo installed --target codex`);
+    const files = record.installedFiles || record.installed_files || [];
+    const plan = buildCodexRemovalPlan(record, files, { operation: 'uninstall', dryRun, force });
+    if (dryRun) {
+      const session = writeCodexSession({
+        operation: 'uninstall',
+        status: 'dry_run',
+        targetTool: 'codex',
+        uuid: record.uuid,
+        title: record.title,
+        sourceUrl: record.sourceUrl || record.source_url,
+        plan,
+        result: { dryRun: true },
+      });
+      const response = { dryRun: true, plan, removedFiles: [], ...session };
+      if (json) outputJson(response);
+      else {
+        info(`Dry run: ${plan.actions.length} file(s) would be removed`);
+        for (const action of plan.actions) {
+          const rel = path.relative(os.homedir(), action.path);
+          log(`  ${action.allowed ? C.dim : C.yellow}•${C.reset} ~/${rel} ${C.dim}${action.reason}${C.reset}`);
+        }
+        log(`  ${C.dim}Session: ${session.sessionPath}${C.reset}`);
+      }
+      return;
+    }
+
+    const result = executeCodexRemovalPlan(plan, { force });
+    if (json) outputJson(result);
+    else {
+      for (const file of result.removedFiles) {
+        success(`Removed: ~/${path.relative(os.homedir(), file.path)}`);
+      }
+      success(`Uninstalled ${record.title || record.uuid}`);
+      log(`  ${C.dim}Manifest: ${CODEX_MANIFEST_FILE}${C.reset}`);
+      log(`  ${C.dim}Session: ${result.sessionPath}${C.reset}\n`);
+    }
+  } catch (e) {
+    error(`Uninstall failed: ${e.message}`);
+  }
+}
+
+function findRollbackSession(selector) {
+  const sessions = readCodexSessions();
+  if (selector === 'last') {
+    return [...sessions].reverse().find(session => (
+      session.operation === 'install'
+      && ['installed', 'staged', 'stage_only'].includes(session.status)
+      && (session.installedFiles?.length || session.result?.stagePath || session.plan?.rollback?.length)
+    ));
+  }
+  const needle = String(selector || '').trim();
+  if (!needle) return null;
+  return sessions.find(session => session.sessionId === needle || String(session.sessionId || '').startsWith(needle));
+}
+
+function filesFromRollbackSession(session) {
+  if (!session) return [];
+  if (session.status === 'staged' && session.result?.stagePath) {
+    return [{ path: session.result.stagePath, sha256: currentFileSha(session.result.stagePath), sourceName: 'install-plan.json' }];
+  }
+  if (Array.isArray(session.installedFiles) && session.installedFiles.length > 0) return session.installedFiles;
+  return (session.plan?.rollback || [])
+    .filter(action => action.type === 'remove_file' && action.path)
+    .map(action => ({ path: action.path, sha256: action.sha256 || '', sourceName: path.basename(action.path) }));
+}
+
+async function cmdRollback() {
+  const args = parseArgs(process.argv);
+  const selector = args.flags.last ? 'last' : (args.flags.session || args.positional[0]);
+  if (!selector) {
+    showRollbackHelp();
+    process.exit(1);
+  }
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') error(`rollback currently supports --target codex only`);
+
+  const json = Boolean(args.flags.json);
+  const dryRun = Boolean(args.flags.dryRun || args.flags.dry_run);
+  const force = Boolean(args.flags.force);
+  if (!json) log(`\n${C.bold}tokrepo rollback${C.reset}\n`);
+
+  try {
+    const session = findRollbackSession(selector);
+    if (!session) error(`No rollback session found for "${selector}". Run: tokrepo installed --target codex --json`);
+    const files = filesFromRollbackSession(session);
+    const plan = buildCodexRemovalPlan(session, files, { operation: 'rollback', dryRun, force });
+    plan.rollbackSessionId = session.sessionId;
+    plan.rollbackSessionPath = session.sessionPath;
+
+    if (dryRun) {
+      const audit = writeCodexSession({
+        operation: 'rollback',
+        status: 'dry_run',
+        targetTool: 'codex',
+        uuid: session.uuid,
+        title: session.title,
+        sourceUrl: session.sourceUrl,
+        plan,
+        result: { dryRun: true },
+      });
+      const response = { dryRun: true, plan, removedFiles: [], ...audit };
+      if (json) outputJson(response);
+      else {
+        info(`Dry run: rollback ${session.sessionId} would remove ${plan.actions.length} file(s)`);
+        for (const action of plan.actions) {
+          const rel = path.relative(os.homedir(), action.path);
+          log(`  ${action.allowed ? C.dim : C.yellow}•${C.reset} ~/${rel} ${C.dim}${action.reason}${C.reset}`);
+        }
+        log(`  ${C.dim}Session: ${audit.sessionPath}${C.reset}`);
+      }
+      return;
+    }
+
+    const result = executeCodexRemovalPlan(plan, { force, removeManifest: Boolean(session.uuid) });
+    if (json) outputJson(result);
+    else {
+      for (const file of result.removedFiles) {
+        success(`Removed: ~/${path.relative(os.homedir(), file.path)}`);
+      }
+      success(`Rolled back ${session.sessionId}`);
+      log(`  ${C.dim}Session: ${result.sessionPath}${C.reset}\n`);
+    }
+  } catch (e) {
+    error(`Rollback failed: ${e.message}`);
+  }
+}
+
 async function cmdOutdated() {
   const args = parseArgs(process.argv);
   const targetTool = validateInstallTarget(args.flags.target || 'codex');
@@ -2384,7 +3267,8 @@ async function cmdOutdated() {
   for (const record of installed) {
     try {
       const { workflow, contents } = await fetchWorkflowForInstall(record.uuid, config, apiBase);
-      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode });
+      const serverPlan = await fetchServerCodexInstallPlan(record.uuid, config, apiBase);
+      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode, serverPlan });
       const diff = diffCodexPlanWithLocal(plan, record);
       if (diff.needsUpdate) {
         list.push({
@@ -2546,12 +3430,15 @@ ${C.bold}USAGE${C.reset}
 ${C.bold}DISCOVER & INSTALL${C.reset}
   ${C.cyan}search${C.reset} <query>      Search assets by keyword
   ${C.cyan}detail${C.reset} <name|uuid>  Show full asset metadata
+  ${C.cyan}plan${C.reset} <name|uuid>    Print agent-native Codex install plan
   ${C.cyan}install${C.reset} <name|uuid> Smart install (auto-detects type & placement)
   ${C.cyan}pull${C.reset} <url|uuid|@u/n> Download raw asset files
   ${C.cyan}clone${C.reset} @username      Clone all assets from a user
   ${C.cyan}installed${C.reset}            List installed Codex assets from manifest
   ${C.cyan}outdated${C.reset}             Check installed Codex assets for updates
   ${C.cyan}sync-installed${C.reset}       Update installed Codex assets from manifest
+  ${C.cyan}uninstall${C.reset} <uuid>     Remove a managed Codex install
+  ${C.cyan}rollback${C.reset} --last      Roll back the latest Codex install session
 
 ${C.bold}PUBLISH${C.reset}
   ${C.cyan}push${C.reset} [files...]     Push files/directory (idempotent upsert)
@@ -2589,8 +3476,9 @@ ${C.bold}INSTALL BEHAVIOR${C.reset}
 
 ${C.bold}EXAMPLES${C.reset}
   tokrepo search "mcp server"                 # Find MCP configs
-  tokrepo search video --json                 # Machine-readable search
+  tokrepo search video --target codex --kind skill --policy allow --json
   tokrepo detail ca000374-f5d8-... --json     # Machine-readable detail
+  tokrepo plan 91aeb22d-eff0-4310-...         # Install plan v2 for agents
   tokrepo install ca000374-f5d8-...           # Install by UUID
   tokrepo install ca000374-f5d8-... --target codex
   tokrepo install c4b18aeb --target gemini    # Install for Gemini CLI
@@ -2599,6 +3487,8 @@ ${C.bold}EXAMPLES${C.reset}
   tokrepo outdated --target codex --json
   tokrepo update --target codex --all
   tokrepo sync-installed --target codex --dry-run
+  tokrepo uninstall 91aeb22d --target codex --dry-run
+  tokrepo rollback --last --target codex --dry-run
   tokrepo push --private my-rules.md          # Save one file privately
   tokrepo push . --kind skill --target codex --install-mode bundle
   tokrepo push --public skill.md              # Share one file publicly
@@ -2626,11 +3516,12 @@ function showSearchHelp() {
 ${C.bold}tokrepo search${C.reset}
 
 USAGE
-  tokrepo search <query> [--json] [--all] [--page-size N] [--sort-by views|latest|stars|popular]
+  tokrepo search <query> [--json] [--all] [--target codex] [--kind skill] [--policy allow|confirm|stage_only|deny] [--page-size N] [--sort-by views|latest|stars|popular]
 
 EXAMPLES
   tokrepo search video
   tokrepo search video --json
+  tokrepo search video --target codex --kind skill --policy allow --json
   tokrepo search "mcp server" --json --all
 `);
 }
@@ -2653,7 +3544,7 @@ function showInstallHelp() {
 ${C.bold}tokrepo install${C.reset}
 
 USAGE
-  tokrepo install <uuid|url|name|pack/slug> [--target gemini|codex] [--yes] [--dry-run] [--stage] [--approve-mcp] [--json]
+  tokrepo install <uuid|url|name|pack/slug> [--target gemini|codex] [--yes] [--dry-run] [--stage] [--approve-mcp] [--verify-commands] [--json]
 
 TARGETS
   codex    Write Codex skills to ~/.codex/skills/<asset-slug>/SKILL.md
@@ -2670,16 +3561,33 @@ EXAMPLES
 `);
 }
 
+function showPlanHelp() {
+  log(`
+${C.bold}tokrepo plan${C.reset}
+
+USAGE
+  tokrepo plan <uuid|url|name> [--target codex] [--stage]
+
+OUTPUT
+  Machine-readable install plan v2 with preconditions, actions, policyDecision,
+  rollback, postVerify, risk metadata, and destination file hashes.
+
+EXAMPLES
+  tokrepo plan 91aeb22d-eff0-4310-abc6-811d2394b420
+  tokrepo plan https://tokrepo.com/en/workflows/91aeb22d-eff0-4310-abc6-811d2394b420
+`);
+}
+
 function showListHelp() {
   log(`
 ${C.bold}tokrepo list${C.reset}
 
 USAGE
-  tokrepo list [--json] [--all] [--page-size N]
+  tokrepo list [--json] [--all] [--target codex] [--kind skill] [--policy allow] [--page-size N]
 
 EXAMPLES
   tokrepo list
-  tokrepo list --json --all
+  tokrepo list --json --all --target codex
 `);
 }
 
@@ -2722,6 +3630,42 @@ EXAMPLES
 `);
 }
 
+function showUninstallHelp() {
+  log(`
+${C.bold}tokrepo uninstall${C.reset}
+
+USAGE
+  tokrepo uninstall <uuid|uuid-prefix|title> --target codex [--dry-run] [--force] [--json]
+
+BEHAVIOR
+  Removes only files recorded in ~/.codex/tokrepo/install-manifest.json and only
+  under ~/.codex/skills or ~/.codex/tokrepo/staged. Local changes are blocked
+  unless --force is provided.
+
+EXAMPLES
+  tokrepo uninstall 91aeb22d --target codex --dry-run --json
+  tokrepo uninstall 91aeb22d-eff0-4310-abc6-811d2394b420 --target codex
+`);
+}
+
+function showRollbackHelp() {
+  log(`
+${C.bold}tokrepo rollback${C.reset}
+
+USAGE
+  tokrepo rollback --last --target codex [--dry-run] [--force] [--json]
+  tokrepo rollback <session-id> --target codex [--dry-run] [--force] [--json]
+
+BEHAVIOR
+  Replays the rollback section from ~/.codex/tokrepo/sessions/<session-id>.json.
+  Local changes are blocked unless --force is provided.
+
+EXAMPLES
+  tokrepo rollback --last --target codex --dry-run --json
+  tokrepo rollback install-20260506-120000-abc123 --target codex
+`);
+}
+
 function showCommandHelp(command) {
   switch (command) {
     case 'search':
@@ -2729,6 +3673,8 @@ function showCommandHelp(command) {
       showSearchHelp(); break;
     case 'detail':
       showDetailHelp(); break;
+    case 'plan':
+      showPlanHelp(); break;
     case 'install':
     case 'i':
       showInstallHelp(); break;
@@ -2741,6 +3687,12 @@ function showCommandHelp(command) {
     case 'installed':
     case 'outdated':
       showSyncInstalledHelp(); break;
+    case 'uninstall':
+    case 'remove':
+    case 'rm':
+      showUninstallHelp(); break;
+    case 'rollback':
+      showRollbackHelp(); break;
     default:
       showHelp(); break;
   }
@@ -2764,12 +3716,15 @@ async function main() {
     case 'pull': await cmdPull(); break;
     case 'search': case 'find': await cmdSearch(); break;
     case 'detail': await cmdDetail(); break;
+    case 'plan': await cmdPlan(); break;
     case 'install': case 'i': await cmdInstall(); break;
     case 'list': await cmdList(); break;
     case 'update': await cmdUpdate(); break;
     case 'delete': await cmdDelete(); break;
     case 'clone': await cmdClone(); break;
     case 'installed': await cmdInstalled(); break;
+    case 'uninstall': case 'remove': case 'rm': await cmdUninstall(); break;
+    case 'rollback': await cmdRollback(); break;
     case 'outdated': await cmdOutdated(); break;
     case 'sync-installed': case 'sync': await cmdSyncInstalled(); break;
     case 'tags': await cmdTags(); break;
@@ -2784,7 +3739,7 @@ async function main() {
   }
 
   // Non-blocking update check after command completes
-  if (!wantsJson(process.argv) && !args.flags.help) {
+  if (command !== 'plan' && !wantsJson(process.argv) && !args.flags.help) {
     checkForUpdate();
   }
 }