tokrepo 3.6.0 → 3.8.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.6.0';
+const CLI_VERSION = '3.8.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 ───
@@ -301,9 +302,10 @@ function parseArgs(argv) {
   }
 
   const valueFlags = new Set([
-    'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'types',
+    'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'query', 'types',
     'kind', 'install-mode', 'install_mode', 'entrypoint', 'asset-kind', 'asset_kind',
-    'version',
+    'version', 'uuid',
+    'policy', 'session',
     'page', 'page-size', 'page_size', 'sort-by', 'sort_by',
     'time-window', 'time_window',
   ]);
@@ -544,14 +546,153 @@ function browserAuthFlow() {
   });
 }
 
-async function cmdPush() {
-  const args = parseArgs(process.argv);
+function inferAssetKindFromPushFiles(files = []) {
+  const normalized = files.map(file => ({
+    ...file,
+    lowerName: String(file.name || '').toLowerCase(),
+    content: String(file.content || ''),
+  }));
+  if (normalized.some(file => /"mcpServers"\s*:/.test(file.content) || /\bmcpServers\s*:/.test(file.content))) return 'mcp_config';
+  if (normalized.some(file => file.type === 'script' || /\.(sh|py|js|mjs|ts|rb|go|rs|lua)$/.test(file.lowerName) || /^#!\//.test(file.content))) return 'script';
+  if (normalized.some(file => file.lowerName === 'package.json' && /"bin"\s*:/.test(file.content))) return 'cli_tool';
+  if (normalized.some(file => file.type === 'skill' || isCodexSkillDocument(file))) return 'skill';
+  if (normalized.some(file => file.type === 'prompt')) return 'prompt';
+  if (normalized.some(file => file.type === 'config')) return 'config';
+  if (normalized.some(file => file.lowerName.endsWith('.md'))) return 'knowledge';
+  return 'other';
+}
 
-  const config = readConfig();
-  if (!config || !config.token) {
-    error(`Not logged in. Run: ${C.cyan}tokrepo login${C.reset}`);
+function analyzePushMetadataQuality(files = [], metadata = {}) {
+  const issues = [];
+  const add = (severity, code, message, fix = '') => {
+    issues.push({ severity, code, message, fix });
+  };
+
+  const normalizedKind = normalizeToolName(metadata.kind || '');
+  const inferredKind = inferAssetKindFromPushFiles(files);
+  const targetTools = parseCsvList(metadata.targetTools).map(normalizeToolName);
+  const installMode = normalizeCodexInstallMode(metadata.installMode);
+  const rawInstallMode = String(metadata.installMode || '').trim();
+  const entrypoint = String(metadata.entrypoint || '').trim();
+  const fileNames = new Set(files.map(file => String(file.name || '').replace(/\\/g, '/')));
+  const lowerFileNames = new Set(Array.from(fileNames).map(name => name.toLowerCase()));
+  const multiFile = files.length > 1;
+  const riskFlags = Array.from(new Set(files.flatMap(file => analyzeInstallRisks(file.name, file.content, file.type))));
+  const containsCodex = targetTools.includes('codex');
+
+  if (!normalizedKind) {
+    add('warning', 'missing_asset_kind', `No asset_kind was provided; inferred "${inferredKind}".`, `Recommended: --kind ${inferredKind}`);
+  } else if (!['skill', 'prompt', 'knowledge', 'mcp_config', 'script', 'cli_tool', 'config', 'pack', 'other'].includes(normalizedKind)) {
+    add('warning', 'unknown_asset_kind', `Unknown asset_kind "${metadata.kind}".`, 'Recommended: use skill, prompt, knowledge, mcp_config, script, cli_tool, config, or pack.');
   }
 
+  if (targetTools.length === 0) {
+    add('warning', 'missing_target_tools', 'No target_tools metadata was provided.', 'Recommended: --target codex or --targets codex,claude_code,gemini_cli.');
+  }
+
+  const invalidTargets = targetTools.filter(tool => !['codex', 'claude_code', 'gemini_cli', 'cursor', 'windsurf', 'opencode'].includes(tool));
+  if (invalidTargets.length > 0) {
+    add('info', 'unknown_target_tool', `Unknown target tool(s): ${invalidTargets.join(', ')}.`, 'Use stable ids when possible: codex, claude_code, gemini_cli, cursor, windsurf.');
+  }
+
+  if (rawInstallMode && !installMode) {
+    add('warning', 'unknown_install_mode', `Unknown install_mode "${metadata.installMode}".`, 'Recommended: single, bundle, split, or stage_only.');
+  } else if (!rawInstallMode && (multiFile || containsCodex)) {
+    add('warning', 'missing_install_mode', `No install_mode was provided for ${multiFile ? 'a multi-file asset' : 'a Codex-targeted asset'}.`, `Recommended: --install-mode ${multiFile ? 'bundle' : 'single'}.`);
+  }
+
+  if (entrypoint && !fileNames.has(entrypoint) && !lowerFileNames.has(entrypoint.toLowerCase())) {
+    add('warning', 'entrypoint_missing', `Entrypoint "${entrypoint}" is not included in the pushed files.`, 'Recommended: set --entrypoint to an included file, usually SKILL.md.');
+  }
+
+  if (!entrypoint && (installMode === 'single' || installMode === 'bundle' || containsCodex)) {
+    add('warning', 'missing_entrypoint', 'No entrypoint metadata was provided.', 'Recommended: --entrypoint SKILL.md or the main markdown file.');
+  }
+
+  const effectiveKind = normalizedKind || inferredKind;
+  if (containsCodex && ['script', 'cli_tool', 'mcp_config'].includes(effectiveKind) && installMode !== 'stage_only') {
+    add('warning', 'high_risk_codex_activation', `${effectiveKind} assets targeted at Codex should stage by default.`, 'Recommended: --install-mode stage_only or publish a markdown skill wrapper.');
+  }
+  if (riskFlags.includes('executable')) {
+    add('warning', 'executes_code_detected', 'Executable code was detected in the asset files.', 'Recommended: declare script/cli_tool or use stage_only for agent installs.');
+  }
+  if (riskFlags.includes('mcp')) {
+    add('warning', 'mcp_config_detected', 'MCP config content was detected.', 'Recommended: --kind mcp_config --install-mode stage_only.');
+  }
+  if (riskFlags.includes('env')) {
+    add('info', 'secret_or_env_mentions', 'Environment variable or secret-like words were mentioned.', 'Check this is documentation only and no real secret is included.');
+  }
+  if (riskFlags.includes('absolute-path')) {
+    add('warning', 'absolute_path_detected', 'Absolute local paths were detected.', 'Recommended: replace machine-specific paths with placeholders.');
+  }
+
+  if (containsCodex && effectiveKind === 'skill') {
+    const skillDocs = files.filter(file => isCodexSkillDocument(file));
+    if (installMode === 'split' && skillDocs.length !== files.length) {
+      add('warning', 'split_requires_skill_docs', 'install_mode=split works best when every markdown file has skill frontmatter.', 'Recommended: use bundle or add name/description frontmatter to each split skill.');
+    }
+    if (skillDocs.length === 0) {
+      add('warning', 'missing_codex_skill_frontmatter', 'No Codex skill frontmatter was found.', 'Recommended: add YAML frontmatter with name and description.');
+    }
+  }
+
+  const severityPenalty = issues.reduce((sum, issue) => {
+    if (issue.severity === 'warning') return sum + 10;
+    return sum + 2;
+  }, 0);
+  const score = Math.max(0, 100 - severityPenalty);
+  const status = issues.some(issue => issue.severity === 'warning') ? 'warn' : 'pass';
+
+  return {
+    score,
+    status,
+    inferredAssetKind: inferredKind,
+    assetKind: normalizedKind || '',
+    targetTools,
+    installMode: installMode || '',
+    entrypoint,
+    riskFlags,
+    issueCount: issues.length,
+    issues,
+  };
+}
+
+function formatMetadataQualityLabel(report) {
+  const color = report.status === 'pass' ? C.green : C.yellow;
+  return `${color}${report.status}${C.reset} ${C.bold}${report.score}/100${C.reset}`;
+}
+
+function printMetadataQualityReport(report, opts = {}) {
+  const compact = Boolean(opts.compact);
+  if (!compact) {
+    log(`\n${C.bold}Agent metadata quality${C.reset}`);
+    log(`  Status: ${formatMetadataQualityLabel(report)}`);
+    log(`  Inferred kind: ${report.inferredAssetKind}`);
+    if (report.targetTools.length) log(`  Targets: ${report.targetTools.join(', ')}`);
+    if (report.installMode) log(`  Install mode: ${report.installMode}`);
+    if (report.riskFlags.length) log(`  Risk flags: ${report.riskFlags.join(', ')}`);
+  } else {
+    log(`${C.bold}Agent metadata quality suggestions:${C.reset}`);
+  }
+
+  if (report.issues.length === 0) {
+    if (!compact) success('Metadata is agent-ready.');
+    return;
+  }
+  for (const issue of report.issues.slice(0, compact ? 8 : report.issues.length)) {
+    const color = issue.severity === 'warning' ? C.yellow : C.dim;
+    log(`  ${color}${issue.severity.toUpperCase()}${C.reset} ${issue.code}: ${issue.message}`);
+    if (issue.fix) log(`    ${C.dim}${issue.fix}${C.reset}`);
+  }
+  if (compact && report.issues.length > 8) {
+    log(`  ${C.dim}...and ${report.issues.length - 8} more suggestion(s). Run --metadata-report for full detail.${C.reset}`);
+  }
+  if (!compact) log('');
+}
+
+async function cmdPush() {
+  const args = parseArgs(process.argv);
+
   const projectConfig = readProjectConfig();
   const baseDir = process.cwd();
 
@@ -621,6 +762,31 @@ async function cmdPush() {
     error('No readable text files found to push.');
   }
 
+  const metadataQuality = analyzePushMetadataQuality(pushFiles, {
+    kind,
+    targetTools,
+    installMode,
+    entrypoint,
+    title,
+    description,
+  });
+
+  if (args.flags.metadata_report || args.flags.metadataReport) {
+    if (args.flags.json) {
+      outputJson({ schemaVersion: 1, metadataQuality, files: pushFiles.map(file => ({ name: file.name, type: file.type, bytes: Buffer.byteLength(file.content || '') })) });
+    } else {
+      printMetadataQualityReport(metadataQuality);
+    }
+    return;
+  }
+
+  // Public registry policy: quality gates advise by default and never block user uploads.
+  // TokRepo-owned CI can opt into strict mode with TOKREPO_METADATA_STRICT=1.
+  if (process.env.TOKREPO_METADATA_STRICT === '1' && metadataQuality.issues.length > 0 && !args.flags.force) {
+    if (!args.flags.json) printMetadataQualityReport(metadataQuality);
+    error(`Internal metadata quality gate failed. Fix the issues or re-run with --force to push anyway.`);
+  }
+
   // Show summary
   log(`\n${C.bold}tokrepo push${C.reset}\n`);
   log(`  ${C.bold}Title:${C.reset}      ${title}`);
@@ -638,6 +804,7 @@ async function cmdPush() {
   if (metadataSummary.length > 0) {
     log(`  ${C.bold}Agent meta:${C.reset} ${metadataSummary.join(' · ')}`);
   }
+  log(`  ${C.bold}Agent quality:${C.reset} ${formatMetadataQualityLabel(metadataQuality)}`);
   log('');
 
   for (const f of pushFiles) {
@@ -648,9 +815,18 @@ async function cmdPush() {
 
   const totalChars = pushFiles.reduce((sum, f) => sum + f.content.length, 0);
 
+  if (metadataQuality.issues.length > 0) {
+    printMetadataQualityReport(metadataQuality, { compact: true });
+  }
+
   // Push
   info('Pushing...');
 
+  const config = readConfig();
+  if (!config || !config.token) {
+    error(`Not logged in. Run: ${C.cyan}tokrepo login${C.reset}`);
+  }
+
   try {
     const data = await apiRequest('POST', '/api/v1/tokenboard/push/upsert', {
       title,
@@ -841,8 +1017,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 +1050,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 +1066,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 +1180,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 +1359,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 +1416,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 +1432,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') {
@@ -1313,7 +1547,36 @@ function mergedPlanRiskProfile(plan) {
   };
 }
 
+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', ''));
@@ -1367,6 +1630,9 @@ function decideCodexPolicy(plan) {
 }
 
 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',
@@ -1380,7 +1646,23 @@ function buildPublicPlanActions(plan) {
   }));
 }
 
+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 = [
@@ -1405,6 +1687,9 @@ function buildPublicPlanPreconditions(plan, policyDecision) {
 }
 
 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) {
@@ -1416,11 +1701,18 @@ function buildPublicPlanRollback(plan) {
 }
 
 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 || [])) {
-    out.push({ type: 'expected_file', path: expected });
+    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 });
@@ -1431,8 +1723,11 @@ function buildPublicPlanPostVerify(plan) {
 function publicInstallPlan(plan) {
   const policyDecision = decideCodexPolicy(plan);
   const actions = buildPublicPlanActions(plan);
+  const schemaVersion = Number(metadataValue(plan.serverPlan, 'schema_version', 'schemaVersion', 2)) || 2;
   return {
-    schemaVersion: 2,
+    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,
@@ -1460,6 +1755,95 @@ 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) {
   const decision = decideCodexPolicy(plan).decision;
   return decision === 'confirm' || decision === 'stage_only' || decision === 'deny';
@@ -1538,6 +1922,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'));
@@ -1546,7 +2026,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 });
   }
@@ -1561,6 +2049,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,
@@ -1573,16 +2064,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 = [];
@@ -1602,8 +2135,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 = {}) {
@@ -1631,6 +2178,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),
   };
@@ -1807,7 +2355,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);
     }
@@ -1821,6 +2370,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) {
@@ -1828,6 +2378,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);
@@ -1836,6 +2387,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`);
       }
     }
@@ -1851,6 +2404,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,
     };
   }
 
@@ -2012,8 +2568,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;
     }
 
@@ -2022,11 +2586,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) {
@@ -2236,13 +2805,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({
@@ -2255,6 +2827,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;
@@ -2383,6 +2958,154 @@ 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;
+  }
+}
+
+function runSelfCliJson(cliArgs, opts = {}) {
+  const childProcess = require('child_process');
+  const stdout = childProcess.execFileSync(process.execPath, [__filename, ...cliArgs], {
+    env: { ...process.env, ...(opts.env || {}), TOKREPO_NONINTERACTIVE: '1' },
+    cwd: opts.cwd || process.cwd(),
+    encoding: 'utf8',
+    maxBuffer: 50 * 1024 * 1024,
+  });
+  return JSON.parse(stdout);
+}
+
+function makeEvalResult(name, ok, details = {}) {
+  return {
+    name,
+    ok: Boolean(ok),
+    status: ok ? 'pass' : 'fail',
+    ...details,
+  };
+}
+
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+}
+
+async function cmdEvalAgent() {
+  const args = parseArgs(process.argv);
+  const json = Boolean(args.flags.json);
+  const sampleUuid = args.flags.uuid || '91aeb22d-eff0-4310-abc6-811d2394b420';
+  const query = args.flags.keyword || args.flags.query || 'video';
+  const keepTemp = Boolean(args.flags.keep_temp || args.flags.keepTemp);
+  const startedAt = new Date().toISOString();
+  const results = [];
+  const tempRoots = [];
+
+  if (!json) log(`\n${C.bold}tokrepo eval-agent${C.reset}\n`);
+
+  const runScenario = async (name, fn) => {
+    const start = Date.now();
+    try {
+      const details = await fn();
+      const result = makeEvalResult(name, true, { durationMs: Date.now() - start, ...details });
+      results.push(result);
+      if (!json) success(`${name} (${result.durationMs}ms)`);
+    } catch (e) {
+      const result = makeEvalResult(name, false, { durationMs: Date.now() - start, error: e.message });
+      results.push(result);
+      if (!json) warn(`${name}: ${e.message}`);
+    }
+  };
+
+  await runScenario('search_filters_codex_allow_skill', async () => {
+    const data = runSelfCliJson(['search', query, '--target', 'codex', '--kind', 'skill', '--policy', 'allow', '--json', '--page-size', '10']);
+    if (!data.count || !Array.isArray(data.list)) throw new Error('filtered search returned no list');
+    const bad = data.list.find(item => item.policyDecision?.decision && item.policyDecision.decision !== 'allow');
+    if (bad) throw new Error(`search returned non-allow asset ${bad.uuid}`);
+    return { count: data.count, firstUuid: data.list[0]?.uuid, firstTitle: data.list[0]?.title };
+  });
+
+  await runScenario('install_plan_contract', async () => {
+    const plan = runSelfCliJson(['plan', sampleUuid, '--target', 'codex']);
+    if (plan.schemaVersion !== 2) throw new Error(`expected schemaVersion 2, got ${plan.schemaVersion}`);
+    if (!plan.policyDecision?.decision) throw new Error('missing policyDecision');
+    if (!Array.isArray(plan.actions) || plan.actions.length === 0) throw new Error('missing actions');
+    if (!Array.isArray(plan.rollback) || plan.rollback.length === 0) throw new Error('missing rollback');
+    if (!Array.isArray(plan.postVerify) || plan.postVerify.length === 0) throw new Error('missing postVerify');
+    return {
+      sourceOfTruth: plan.sourceOfTruth,
+      concretePlanSource: plan.concretePlanSource,
+      policy: plan.policyDecision.decision,
+      actions: plan.actions.length,
+    };
+  });
+
+  await runScenario('metadata_quality_report_non_blocking', async () => {
+    const tmp = createTempDir('tokrepo-eval-quality');
+    tempRoots.push(tmp);
+    const skillPath = path.join(tmp, 'SKILL.md');
+    fs.writeFileSync(skillPath, `---\nname: eval-agent-sample\ndescription: \"Sample skill used by tokrepo eval-agent.\"\n---\n\n# Eval Agent Sample\n\nUse this to test metadata quality reporting.\n`);
+    const report = runSelfCliJson(['push', skillPath, '--metadata-report', '--json', '--kind', 'skill', '--target', 'codex', '--install-mode', 'single', '--entrypoint', 'SKILL.md']);
+    if (!report.metadataQuality) throw new Error('missing metadataQuality');
+    if (report.metadataQuality.status !== 'pass') throw new Error(`expected pass, got ${report.metadataQuality.status}`);
+    return { score: report.metadataQuality.score, status: report.metadataQuality.status };
+  });
+
+  await runScenario('codex_install_verify_and_rollback', async () => {
+    const tmpHome = createTempDir('tokrepo-eval-home');
+    tempRoots.push(tmpHome);
+    const env = { HOME: tmpHome };
+    const install = runSelfCliJson(['install', sampleUuid, '--target', 'codex', '--yes', '--json'], { env });
+    if (!install.sessionId) throw new Error('install did not create sessionId');
+    if (!install.verification?.ok) throw new Error('install verification failed');
+    if (!install.installedFiles?.length) throw new Error('no files installed');
+    const installed = runSelfCliJson(['installed', '--target', 'codex', '--json'], { env });
+    if (installed.count < 1) throw new Error('installed manifest did not record asset');
+    const rollback = runSelfCliJson(['rollback', '--last', '--target', 'codex', '--json'], { env });
+    if (!rollback.removedFiles?.length) throw new Error('rollback removed no files');
+    const after = runSelfCliJson(['installed', '--target', 'codex', '--json'], { env });
+    if (after.count !== 0) throw new Error(`manifest still has ${after.count} install(s) after rollback`);
+    return {
+      installedFiles: install.installedFiles.length,
+      sessionId: install.sessionId,
+      removedFiles: rollback.removedFiles.length,
+    };
+  });
+
+  if (!keepTemp) {
+    for (const dir of tempRoots) {
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+  }
+
+  const failed = results.filter(result => !result.ok);
+  const summary = {
+    schemaVersion: 1,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    cliVersion: CLI_VERSION,
+    targetTool: 'codex',
+    sampleUuid,
+    query,
+    status: failed.length === 0 ? 'pass' : 'fail',
+    passed: results.length - failed.length,
+    failed: failed.length,
+    count: results.length,
+    tempRoots: keepTemp ? tempRoots : [],
+    results,
+  };
+
+  if (json) {
+    outputJson(summary);
+  } else {
+    log('');
+    if (summary.status === 'pass') success(`Agent eval passed: ${summary.passed}/${summary.count}`);
+    else warn(`Agent eval failed: ${summary.failed}/${summary.count}`);
+  }
+
+  if (failed.length > 0) process.exitCode = 1;
+}
+
 async function cmdSyncInstalled() {
   const args = parseArgs(process.argv);
   const targetTool = validateInstallTarget(args.flags.target || 'codex');
@@ -2417,7 +3140,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;
 
@@ -2455,8 +3179,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({
@@ -2468,6 +3194,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) {
@@ -2526,6 +3255,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',
@@ -2549,6 +3280,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');
@@ -2574,7 +3580,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({
@@ -2743,6 +3750,9 @@ ${C.bold}DISCOVER & INSTALL${C.reset}
   ${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.cyan}eval-agent${C.reset}           Run agent-native contract and lifecycle evals
 
 ${C.bold}PUBLISH${C.reset}
   ${C.cyan}push${C.reset} [files...]     Push files/directory (idempotent upsert)
@@ -2768,6 +3778,7 @@ ${C.bold}PUSH OPTIONS${C.reset}
   ${C.cyan}--kind${C.reset} skill         Set agent asset_kind
   ${C.cyan}--target${C.reset} codex       Add target tool metadata on push
   ${C.cyan}--install-mode${C.reset} bundle Set install_mode metadata
+  ${C.cyan}--metadata-report${C.reset}    Print agent metadata quality suggestions without pushing
 
 ${C.bold}INSTALL BEHAVIOR${C.reset}
   Skills   → .claude/skills/    (if .claude/ exists)
@@ -2780,7 +3791,7 @@ ${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
@@ -2791,7 +3802,11 @@ ${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 eval-agent --json
   tokrepo push --private my-rules.md          # Save one file privately
+  tokrepo push . --metadata-report --json     # Check agent metadata without uploading
   tokrepo push . --kind skill --target codex --install-mode bundle
   tokrepo push --public skill.md              # Share one file publicly
   tokrepo push --private .                    # Push current dir as private
@@ -2818,11 +3833,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
 `);
 }
@@ -2845,7 +3861,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
@@ -2884,11 +3900,11 @@ function showListHelp() {
 ${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
 `);
 }
 
@@ -2931,6 +3947,61 @@ 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 showEvalAgentHelp() {
+  log(`
+${C.bold}tokrepo eval-agent${C.reset}
+
+USAGE
+  tokrepo eval-agent [--json] [--uuid <asset-uuid>] [--keyword video] [--keep-temp]
+
+BEHAVIOR
+  Runs agent-native smoke evals against search filters, install-plan contracts,
+  metadata quality reporting, Codex install verification, manifest state, and rollback.
+  Lifecycle tests use a temporary HOME and do not touch your real ~/.codex.
+
+EXAMPLES
+  tokrepo eval-agent
+  tokrepo eval-agent --json
+  tokrepo eval-agent --uuid 91aeb22d-eff0-4310-abc6-811d2394b420 --keyword video --json
+`);
+}
+
 function showCommandHelp(command) {
   switch (command) {
     case 'search':
@@ -2952,6 +4023,15 @@ function showCommandHelp(command) {
     case 'installed':
     case 'outdated':
       showSyncInstalledHelp(); break;
+    case 'uninstall':
+    case 'remove':
+    case 'rm':
+      showUninstallHelp(); break;
+    case 'rollback':
+      showRollbackHelp(); break;
+    case 'eval-agent':
+    case 'eval':
+      showEvalAgentHelp(); break;
     default:
       showHelp(); break;
   }
@@ -2982,6 +4062,9 @@ async function main() {
     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 'eval-agent': case 'eval': await cmdEvalAgent(); break;
     case 'outdated': await cmdOutdated(); break;
     case 'sync-installed': case 'sync': await cmdSyncInstalled(); break;
     case 'tags': await cmdTags(); break;