@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-token-savior-budget.mjs

@@ -0,0 +1,370 @@
+import crypto from 'node:crypto';
+
+const tokenSaviorStage = 'Stage 128';
+const tokenSaviorKind = 'token-savior-entry-budget-contract';
+
+const budgetProfiles = {
+  tiny_entry: {
+    max_context_tokens: 900,
+    entry_instruction_tokens: 180,
+    contract_summary_tokens: 280,
+    evidence_summary_tokens: 180,
+    command_preview_tokens: 160,
+    reserved_tokens: 100,
+    target: 'Expose only the routing sentence, one selected workflow, and the minimum local evidence pointer.',
+  },
+  balanced_runtime: {
+    max_context_tokens: 1800,
+    entry_instruction_tokens: 260,
+    contract_summary_tokens: 520,
+    evidence_summary_tokens: 420,
+    command_preview_tokens: 360,
+    reserved_tokens: 240,
+    target: 'Expose the next workflow, the relevant contract, compact evidence summary, and command previews.',
+  },
+  full_maintenance: {
+    max_context_tokens: 3200,
+    entry_instruction_tokens: 360,
+    contract_summary_tokens: 920,
+    evidence_summary_tokens: 900,
+    command_preview_tokens: 620,
+    reserved_tokens: 400,
+    target: 'Expose broader maintenance context only when review, release, or regression work needs it.',
+  },
+};
+
+export function runtimeTokenSaviorBudget({ prompt = '', friction = null, source = {} } = {}) {
+  const normalizedPrompt = normalizePrompt(prompt);
+  const normalizedFriction = normalizeFriction(friction);
+  const recommendedProfile = selectProfile(normalizedPrompt, normalizedFriction);
+  const contextBudget = contextBudgetForProfile(recommendedProfile);
+  const skillsToSurface = skillsToSurfaceFor({ prompt: normalizedPrompt, friction: normalizedFriction, profile: recommendedProfile });
+  const skillsToDefer = skillsToDeferFor(skillsToSurface, recommendedProfile);
+  const commandsToSurface = commandsToSurfaceFor({ prompt: normalizedPrompt, friction: normalizedFriction, profile: recommendedProfile });
+  const core = {
+    version: 1,
+    stage: tokenSaviorStage,
+    budget_kind: tokenSaviorKind,
+    source_bindings: sourceBindingSummary(source, normalizedPrompt, normalizedFriction),
+    prompt_summary: promptSummary(normalizedPrompt),
+    friction_summary: frictionSummary(normalizedFriction),
+    recommended_profile: recommendedProfile,
+    skills_to_surface: skillsToSurface,
+    skills_to_defer: skillsToDefer,
+    commands_to_surface: commandsToSurface,
+    context_budget: contextBudget,
+    token_saving_reasoning: tokenSavingReasoning({ prompt: normalizedPrompt, friction: normalizedFriction, profile: recommendedProfile }),
+    budget_application_order: budgetApplicationOrder(recommendedProfile),
+    boundary_assertions: runtimeTokenSaviorBudgetBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeTokenSaviorBudgetInvariants(core);
+  const budget = {
+    ...core,
+    ok: invariants.pass,
+    token_savior_budget_invariants: invariants,
+  };
+  return {
+    ...budget,
+    budget_digest: digestTokenSaviorBudget(runtimeTokenSaviorBudgetDigestPayload(budget)),
+  };
+}
+
+export function runtimeTokenSaviorBudgetDigestPayload(budget) {
+  return {
+    stage: budget.stage,
+    budget_kind: budget.budget_kind,
+    source_bindings: budget.source_bindings,
+    prompt_summary: budget.prompt_summary,
+    friction_summary: budget.friction_summary,
+    recommended_profile: budget.recommended_profile,
+    skills_to_surface: budget.skills_to_surface,
+    skills_to_defer: budget.skills_to_defer,
+    commands_to_surface: budget.commands_to_surface,
+    context_budget: budget.context_budget,
+    token_saving_reasoning: budget.token_saving_reasoning,
+    budget_application_order: budget.budget_application_order,
+    boundary_assertions: budget.boundary_assertions,
+    token_savior_budget_invariants: budget.token_savior_budget_invariants,
+  };
+}
+
+export function runtimeTokenSaviorBudgetBoundaryAssertions() {
+  return {
+    token_savior_budget_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    source_write: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    verification_execution: false,
+    runtime_action: false,
+    workflow_execution: false,
+    skill_execution: false,
+    auto_execution: false,
+    repair_execution: false,
+    command_mutation: false,
+    shell_interception: false,
+    output_mutation: false,
+    dynamic_tool_execution: false,
+    embeddings: false,
+    remote_config: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeTokenSaviorBudgetInvariants(budget) {
+  const validProfiles = Object.keys(budgetProfiles);
+  const unsafeBoundaries = Object.entries(budget.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingForbidden = ['command_execution', 'workflow_execution', 'skill_execution', 'runtime_action', 'dynamic_tool_execution', 'embeddings', 'remote_config', 'external_network', 'model_invocation', 'platform_api', 'git', 'git_write', 'commit', 'pr', 'push', 'merge', 'subagent', 'mcp', 'business_source_write', 'state_directory_created']
+    .filter((key) => budget.boundary_assertions?.[key] !== false);
+  const commandExecutors = budget.commands_to_surface
+    .filter((item) => item.preview_only !== true || /(^|\s)(--confirm|--run|--once|--auto-run|git\s+(commit|push|merge|tag)|gh\s+pr)(\s|$)/i.test(item.command))
+    .map((item) => item.id);
+  const budgetTotal = Object.entries(budget.context_budget || {})
+    .filter(([key]) => key !== 'max_context_tokens' && (key.endsWith('_tokens') || key === 'reserved_tokens'))
+    .reduce((sum, [, value]) => sum + numberValue(value), 0);
+  const findings = [
+    ...(budget.stage === tokenSaviorStage ? [] : [`stage must be ${tokenSaviorStage}`]),
+    ...(budget.budget_kind === tokenSaviorKind ? [] : [`budget_kind must be ${tokenSaviorKind}`]),
+    ...(budget.source_bindings?.prompt_digest ? [] : ['source prompt digest is required']),
+    ...(validProfiles.includes(budget.recommended_profile) ? [] : [`recommended_profile must be one of ${validProfiles.join(', ')}`]),
+    ...(Array.isArray(budget.skills_to_surface) && budget.skills_to_surface.length > 0 ? [] : ['skills_to_surface must contain at least one skill']),
+    ...(Array.isArray(budget.skills_to_defer) ? [] : ['skills_to_defer must be a list']),
+    ...(Array.isArray(budget.commands_to_surface) && budget.commands_to_surface.length > 0 ? [] : ['commands_to_surface must contain at least one preview command']),
+    ...(budget.context_budget?.max_context_tokens >= budgetTotal ? [] : ['context budget line items must fit max_context_tokens']),
+    ...(Array.isArray(budget.token_saving_reasoning) && budget.token_saving_reasoning.length > 0 ? [] : ['token_saving_reasoning must explain the recommendation']),
+    ...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+    ...missingForbidden.map((key) => `forbidden boundary missing or not false: ${key}`),
+    ...commandExecutors.map((id) => `commands_to_surface must remain preview-only and non-executing: ${id}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: ['prompt_binding', 'profile_selection', 'skills_surface_defer_split', 'command_preview_only', 'context_budget_bounds', 'read_only_boundary_assertions'],
+    findings,
+  };
+}
+
+export function digestTokenSaviorBudget(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function normalizePrompt(prompt) {
+  const text = String(prompt || '').trim();
+  return {
+    text,
+    lower: text.toLowerCase(),
+    length: text.length,
+    estimated_tokens: estimateTokens(text),
+    digest: digestTokenSaviorBudget({ prompt: text }),
+  };
+}
+
+function normalizeFriction(input) {
+  if (!input) return { provided: false, friction_score: 0, friction_level: 'not_provided', priority_fixes: [], dimensions: [], top_friction: '' };
+  const matrix = objectValue(input.experience_friction_matrix || input);
+  const dimensions = listValue(matrix.dimensions).map((dimension) => ({
+    id: stringValue(dimension.id),
+    severity: stringValue(dimension.severity || 'low'),
+    score: numberValue(dimension.score),
+  })).filter((dimension) => dimension.id);
+  const priorityFixes = listValue(matrix.priority_fixes).map((fix) => ({
+    id: stringValue(fix.id),
+    severity: stringValue(fix.severity || 'low'),
+    score: numberValue(fix.score),
+    recommended_stage: stringValue(fix.recommended_stage),
+  })).filter((fix) => fix.id);
+  return {
+    provided: true,
+    stage: stringValue(matrix.stage || 'Stage 126'),
+    friction_score: numberValue(matrix.friction_score),
+    friction_level: stringValue(matrix.friction_level || 'unknown'),
+    priority_fixes: priorityFixes,
+    dimensions,
+    top_friction: priorityFixes[0]?.id || dimensions.sort((left, right) => right.score - left.score)[0]?.id || '',
+    friction_digest: stringValue(matrix.friction_digest || input.friction_digest),
+  };
+}
+
+function selectProfile(prompt, friction) {
+  const highFriction = friction.friction_score >= 60 || ['high', 'severe'].includes(friction.friction_level);
+  const tokenPain = hasAny(prompt.lower, ['token', 'context', '上下文', '省 token', '节省', '预算']) || hasFriction(friction, 'token_overhead');
+  const releaseOrReview = hasAny(prompt.lower, ['review', 'release', 'commit', 'regression', '回归', '提交', '发布', '审查']) || hasFriction(friction, 'completion_claim_risk') || hasFriction(friction, 'superpowers_parity_gap');
+  const quickEntry = hasAny(prompt.lower, ['start', 'entry', 'next', '下一步', '入口', '继续']) || hasFriction(friction, 'entry_confusion') || hasFriction(friction, 'next_action_unclear');
+  if (releaseOrReview && highFriction) return 'full_maintenance';
+  if (tokenPain && quickEntry && !releaseOrReview) return 'tiny_entry';
+  if (prompt.estimated_tokens <= 40 && (quickEntry || tokenPain) && friction.friction_score < 70) return 'tiny_entry';
+  if (releaseOrReview) return 'full_maintenance';
+  return 'balanced_runtime';
+}
+
+function contextBudgetForProfile(profileName) {
+  const profile = budgetProfiles[profileName] || budgetProfiles.balanced_runtime;
+  return {
+    max_context_tokens: profile.max_context_tokens,
+    entry_instruction_tokens: profile.entry_instruction_tokens,
+    contract_summary_tokens: profile.contract_summary_tokens,
+    evidence_summary_tokens: profile.evidence_summary_tokens,
+    command_preview_tokens: profile.command_preview_tokens,
+    reserved_tokens: profile.reserved_tokens,
+    target: profile.target,
+  };
+}
+
+function skillsToSurfaceFor({ prompt, friction, profile }) {
+  const surface = new Set(['using-vibecoding']);
+  if (profile !== 'tiny_entry') surface.add('vibe-writing-plans');
+  if (hasFriction(friction, 'evidence_gap') || hasFriction(friction, 'completion_claim_risk') || hasAny(prompt.lower, ['verify', 'evidence', '验证', '证据'])) surface.add('vibe-test-driven-development');
+  if (hasFriction(friction, 'command_discovery_cost') || hasAny(prompt.lower, ['command', 'script', '命令', '脚本'])) surface.add('vibe-executing-plans');
+  if (hasFriction(friction, 'superpowers_parity_gap') || hasAny(prompt.lower, ['review', 'regression', '回归', '审查'])) surface.add('vibe-review');
+  return [...surface].map((skill) => ({ skill, reason: skillReason(skill, friction) }));
+}
+
+function skillsToDeferFor(surface, profile) {
+  const surfaced = new Set(surface.map((item) => item.skill));
+  const all = ['vibe-writing-plans', 'vibe-executing-plans', 'vibe-test-driven-development', 'vibe-review', 'vibe-implementation', 'vibe-systematic-debugging', 'vibe-receiving-code-review', 'vibe-writing-skills'];
+  return all
+    .filter((skill) => !surfaced.has(skill))
+    .map((skill) => ({
+      skill,
+      reason: profile === 'tiny_entry'
+        ? 'Deferred to keep the entry budget under tiny_entry until the user selects the next workflow lane.'
+        : 'Deferred until local evidence shows this skill is needed for the selected workflow step.',
+    }));
+}
+
+function commandsToSurfaceFor({ friction, profile }) {
+  const commands = [
+    { id: 'start-runtime-entry', command: 'node tools/vibe-runtime/index.mjs workflow --start --prompt <text> --json --root <repo-root>', reason: 'Reproduce visible entry routing before loading broader context.' },
+    { id: 'show-token-budget', command: 'node tools/vibe-runtime/index.mjs tokens --savior-budget --prompt <text> --json --root <repo-root>', reason: 'Recompute this budget from the same prompt without executing actions.' },
+  ];
+  if (friction.provided) commands.push({ id: 'bind-friction-budget', command: 'node tools/vibe-runtime/index.mjs tokens --savior-budget --prompt <text> --from-friction <stage126-friction.json> --json --root <repo-root>', reason: 'Bind budget selection to local Stage 126 friction evidence.' });
+  if (profile !== 'tiny_entry') commands.push({ id: 'next-action-console', command: 'node tools/vibe-runtime/index.mjs workflow --next-action-console --from-friction <stage126-friction.json> --json --root <repo-root>', reason: 'Use one-screen guidance before reading wider docs.' });
+  return commands.map((item) => ({ ...item, preview_only: true, execute: false }));
+}
+
+function tokenSavingReasoning({ prompt, friction, profile }) {
+  const reasons = [
+    `profile=${profile} selected from prompt_tokens=${prompt.estimated_tokens} and friction_score=${friction.friction_score}`,
+    'Only the entry skill, selected contract summary, compact evidence summary, and preview commands should be surfaced initially.',
+    'Deferred skills remain available by explicit follow-up instead of being loaded into the entry context.',
+  ];
+  if (friction.provided) reasons.push(`friction evidence bound from Stage 126 with top_friction=${friction.top_friction || 'none'}`);
+  if (hasFriction(friction, 'token_overhead')) reasons.push('token_overhead friction prioritizes tiny or balanced context before broader maintenance context.');
+  return reasons;
+}
+
+function budgetApplicationOrder(profile) {
+  const order = [
+    'surface using-vibecoding entry sentence first',
+    'surface only the selected runtime command synopsis',
+    'summarize local evidence by digest and blocker count instead of raw logs',
+    'defer non-selected workflow skills until the next explicit manual step',
+  ];
+  if (profile === 'full_maintenance') order.push('allow broader contract summary only after review/release/regression intent is explicit');
+  return order;
+}
+
+function promptSummary(prompt) {
+  return {
+    provided: prompt.length > 0,
+    character_count: prompt.length,
+    estimated_tokens: prompt.estimated_tokens,
+    prompt_digest: prompt.digest,
+  };
+}
+
+function frictionSummary(friction) {
+  return {
+    provided: friction.provided,
+    stage: friction.stage || '',
+    friction_score: friction.friction_score,
+    friction_level: friction.friction_level,
+    top_friction: friction.top_friction,
+    priority_fix_count: friction.priority_fixes.length,
+    friction_digest: friction.friction_digest,
+  };
+}
+
+function sourceBindingSummary(source, prompt, friction) {
+  return {
+    prompt_digest: prompt.digest,
+    prompt_estimated_tokens: prompt.estimated_tokens,
+    friction_file: stringValue(source.friction_file),
+    friction_file_digest: stringValue(source.friction_digest),
+    friction_matrix_digest: friction.friction_digest,
+    source_kind: friction.provided ? 'prompt-plus-stage126-friction' : 'prompt-only',
+  };
+}
+
+function skillReason(skill, friction) {
+  const reasons = {
+    'using-vibecoding': 'Always surface the lightweight entry contract first.',
+    'vibe-writing-plans': 'Needed when the prompt or friction indicates planning or contract shaping.',
+    'vibe-executing-plans': 'Needed when command discovery or staged execution friction is present.',
+    'vibe-test-driven-development': 'Needed when local verification or evidence binding is the next bottleneck.',
+    'vibe-review': 'Needed when review, regression, or completion-claim risk is present.',
+  };
+  return reasons[skill] || `Surfaced because top friction is ${friction.top_friction || 'not provided'}.`;
+}
+
+function hasFriction(friction, id) {
+  return friction.priority_fixes.some((fix) => fix.id === id) || friction.dimensions.some((dimension) => dimension.id === id && dimension.score >= 50);
+}
+
+function hasAny(text, needles) {
+  return needles.some((needle) => text.includes(String(needle).toLowerCase()));
+}
+
+function estimateTokens(text) {
+  return Math.ceil(String(text || '').length / 4);
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function stringValue(value) {
+  return String(value || '').trim();
+}
+
+function numberValue(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function stableStringify(value) {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sortValue(item)]));
+  }
+  return value;
+}

package/tools/vibe-runtime/runtime-tokens-command-deps.mjs

@@ -0,0 +1,17 @@
+export function runtimeTokensCommandDeps(deps) {
+  return {
+    ensureRoot: deps.ensureRoot,
+    printList: deps.printList,
+    printTokenSaviorBudget: deps.printTokenSaviorBudget,
+    tokenAdviceEnvelope: deps.tokenAdviceEnvelope,
+    tokenAuditEnvelope: deps.tokenAuditEnvelope,
+    tokenCompactionEnvelope: deps.tokenCompactionEnvelope,
+    tokenMetricsEnvelope: deps.tokenMetricsEnvelope,
+    tokenProfileEnvelope: deps.tokenProfileEnvelope,
+    tokenRewritePreviewEnvelope: deps.tokenRewritePreviewEnvelope,
+    tokenSaviorBudgetEnvelope: deps.tokenSaviorBudgetEnvelope,
+    writeJsonEnvelope: deps.writeJsonEnvelope,
+    writeTokenCompaction: deps.writeTokenCompaction,
+    writeTokenMetrics: deps.writeTokenMetrics,
+  };
+}

package/tools/vibe-runtime/runtime-tokens-command.mjs

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { runContextBudgetEntryDefaultsCommand } from './runtime-context-budget-entry-defaults-command.mjs';
+import { printTokens } from './runtime-tokens-presentation.mjs';
+
+const runtimeTokensContractSurfaces = Object.freeze(['runtime-cli-usage', 'tools/vibe-runtime-check/index.mjs']);
+
+export function runTokensCommand(deps, options) {
+  const {
+    ensureRoot,
+    printList,
+    printTokenSaviorBudget,
+    tokenAdviceEnvelope,
+    tokenAuditEnvelope,
+    tokenCompactionEnvelope,
+    tokenMetricsEnvelope,
+    tokenProfileEnvelope,
+    tokenRewritePreviewEnvelope,
+    tokenSaviorBudgetEnvelope,
+    writeJsonEnvelope,
+    writeTokenCompaction,
+    writeTokenMetrics,
+  } = deps;
+  if (!runtimeTokensContractSurfaces.includes('tools/vibe-runtime-check/index.mjs')) throw new Error('runtime tokens contract marker missing');
+
+  validateTokensCommandOptions(options);
+  ensureRoot(options.root);
+  if (options.tokensCatalog) {
+    if (options.confirm || options.dryRun) throw new Error('tokens catalog is read-only');
+    const envelope = tokenAuditEnvelope(options.root, 'catalog');
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokens({ printList }, envelope);
+    return;
+  }
+  if (options.tokensProfile) {
+    if (options.confirm || options.dryRun) throw new Error('tokens profile is read-only');
+    const envelope = tokenProfileEnvelope(options.tokenProfileName || 'balanced');
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokens({ printList }, envelope);
+    return;
+  }
+  if (options.tokensAdvice) {
+    if (options.confirm || options.dryRun || options.preflight || options.dispatch || options.dispatchIntent) throw new Error('tokens advice is read-only and does not accept execution, dispatch, preview, or write flags');
+    const envelope = tokenAdviceEnvelope(options.root, { intent: options.methodologyIntent, commandName: options.tokenCommandName });
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokens({ printList }, envelope);
+    return;
+  }
+  if (options.tokensSaviorBudget) {
+    if (options.confirm || options.dryRun || options.preflight || options.dispatch || options.dispatchIntent) throw new Error('tokens --savior-budget is read-only and does not accept execution, dispatch, preview, dry-run, confirm, or write flags');
+    if (!options.prompt) throw new Error('tokens --savior-budget requires --prompt <text>');
+    const envelope = tokenSaviorBudgetEnvelope(options.root, { prompt: options.prompt, frictionFile: options.fromFriction });
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokenSaviorBudget(envelope);
+    return;
+  }
+  if (options.tokensEntryDefaults) {
+    runContextBudgetEntryDefaultsCommand(options, { writeJsonEnvelope });
+    return;
+  }
+  if (options.tokensRewritePreview) {
+    if (options.confirm) throw new Error('tokens rewrite preview is read-only');
+    if (!options.tokenCommandName) throw new Error('tokens --rewrite-preview requires --command <cmd>');
+    const envelope = tokenRewritePreviewEnvelope(options.tokenCommandName);
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokens({ printList }, envelope);
+    return;
+  }
+  if (options.tokensMetrics) {
+    if (options.confirm && options.dryRun) throw new Error('tokens --metrics accepts either --preview or --confirm, not both');
+    if (options.tokenCompactionFiles.length === 0) throw new Error('tokens --metrics requires --from-compactions <token-compaction-file...>');
+    const envelope = tokenMetricsEnvelope(options.root, { compactionFiles: options.tokenCompactionFiles, persist: options.confirm });
+    if (options.confirm) {
+      const file = writeTokenMetrics(options.root, envelope);
+      if (options.json) writeJsonEnvelope('tokens', { ...envelope, token_file: path.basename(file), token_metrics_file: path.basename(file) });
+      else printTokens({ printList }, envelope, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokens({ printList }, envelope);
+    return;
+  }
+  if (options.tokensCompactOutput) {
+    if (options.confirm && options.dryRun) throw new Error('tokens --compact-output accepts either --preview or --confirm, not both');
+    if (!options.tokenCommandName) throw new Error('tokens --compact-output requires --command <cmd-name>');
+    if (!options.fromFile) throw new Error('tokens --compact-output requires --from-file <output-file>');
+    const envelope = tokenCompactionEnvelope(options.root, { commandName: options.tokenCommandName, outputFile: options.fromFile, persist: options.confirm });
+    if (options.confirm) {
+      const file = writeTokenCompaction(options.root, envelope);
+      if (options.json) writeJsonEnvelope('tokens', { ...envelope, token_file: path.basename(file), token_compaction_file: path.basename(file) });
+      else printTokens({ printList }, envelope, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('tokens', envelope);
+    else printTokens({ printList }, envelope);
+    return;
+  }
+  if (options.confirm || options.dryRun) throw new Error('tokens verification is read-only');
+  const envelope = tokenAuditEnvelope(options.root, 'verify', options.tokenFile);
+  if (options.json) writeJsonEnvelope('tokens', envelope);
+  else printTokens({ printList }, envelope);
+}
+
+function validateTokensCommandOptions(options) {
+  const unsafeTokenRuntimeFlags = options.write || options.scan || options.once || options.fromDispatch || options.dispatchEvent || options.actor || options.approval || options.run || options.autoRun;
+  if (options.tokensSaviorBudget && unsafeTokenRuntimeFlags) throw new Error('tokens --savior-budget is read-only and does not accept execution, dispatch, preview, dry-run, confirm, or write flags');
+  if (options.tokensEntryDefaults && unsafeTokenRuntimeFlags) throw new Error('tokens --entry-defaults is read-only and does not accept execution, dispatch, preview, dry-run, confirm, or write flags');
+  if (unsafeTokenRuntimeFlags) throw new Error('tokens supports deterministic compaction, advice, profiles, metrics, rewrite preview, catalog, savior budget, entry defaults, and read-only verification only');
+
+  const modes = [options.tokensCatalog, options.tokensCompactOutput, options.tokensProfile, options.tokensAdvice, options.tokensSaviorBudget, options.tokensEntryDefaults, options.tokensMetrics, options.tokensRewritePreview, options.tokensVerify].filter(Boolean);
+  if (modes.length !== 1) throw new Error('tokens requires exactly one of --catalog, --compact-output, --profile, --advice, --savior-budget, --entry-defaults, --metrics, --rewrite-preview, or --verify');
+  if (options.methodologyIntent && !options.tokensAdvice) throw new Error('--intent is only supported by tokens --advice');
+  if (options.tokenCommandName && !options.tokensCompactOutput && !options.tokensRewritePreview && !options.tokensAdvice) throw new Error('--command is only supported by tokens --compact-output, --rewrite-preview, or --advice');
+  if (options.prompt && !options.tokensSaviorBudget && !options.tokensEntryDefaults) throw new Error('--prompt is only supported by tokens --savior-budget');
+  if (options.fromFriction && !options.tokensSaviorBudget) throw new Error('--from-friction is only supported by tokens --savior-budget');
+  if (options.fromBudget && !options.tokensEntryDefaults) throw new Error('--from-budget is only supported by tokens --entry-defaults');
+  if (options.fromScorecard && !options.tokensEntryDefaults) throw new Error('--from-scorecard is only supported by tokens --entry-defaults');
+}

package/tools/vibe-runtime/runtime-tokens-presentation.mjs

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import process from 'node:process';
+
+export function printTokens({ printList }, envelope, file = '') {
+  console.log('Vibecoding Runtime Token Economy');
+  console.log(`Mode: ${envelope.mode}`);
+  if (envelope.token_compaction) {
+    console.log(`Command: ${envelope.token_compaction.command_name}; Compactor: ${envelope.token_compaction.compactor_id}`);
+    console.log(`Estimated tokens: ${envelope.token_compaction.metrics.estimated_input_tokens} -> ${envelope.token_compaction.metrics.estimated_output_tokens}; savings=${envelope.token_compaction.metrics.savings_ratio}`);
+    if (file) console.log(`Token compaction: ${path.relative(process.cwd(), file)}`);
+    console.log('Compacted output:');
+    console.log(envelope.token_compaction.compacted_text);
+  } else if (envelope.token_metrics) {
+    console.log(`Compactions: ${envelope.token_metrics.totals.compaction_count}; savings=${envelope.token_metrics.totals.savings_ratio}`);
+    console.log(`Estimated tokens: ${envelope.token_metrics.totals.estimated_input_tokens} -> ${envelope.token_metrics.totals.estimated_output_tokens}; saved=${envelope.token_metrics.totals.estimated_tokens_saved}`);
+    if (file) console.log(`Token metrics: ${path.relative(process.cwd(), file)}`);
+  } else if (envelope.token_advice) {
+    console.log(`Intent: ${envelope.token_advice.intent}; Profile: ${envelope.token_advice.recommended_profile}`);
+    if (envelope.token_advice.command) console.log(`Command: ${envelope.token_advice.command}`);
+    console.log(`Compactors: ${envelope.token_advice.recommended_compactors.map((compactor) => compactor.id).join(', ') || 'none'}`);
+    console.log(`Rewrites: ${envelope.token_advice.recommended_rewrites.map((rewrite) => rewrite.suggested_command).join(', ') || 'none'}`);
+    console.log(`Digest: ${envelope.token_advice.advice_digest}`);
+  } else if (envelope.profile) {
+    console.log(`Profile: ${envelope.profile.name}; Budget: ${envelope.profile.output_budget}`);
+    console.log(`Target: ${envelope.profile.target}`);
+    console.log(`Digest: ${envelope.profile.profile_digest}`);
+  } else if (envelope.rewrite_preview) {
+    console.log(`Command: ${envelope.rewrite_preview.command}`);
+    console.log(`Suggested: ${envelope.rewrite_preview.suggested_command}`);
+    console.log(`Changed: ${envelope.rewrite_preview.changed ? 'yes' : 'no'}; Rule: ${envelope.rewrite_preview.rule}`);
+  } else if (envelope.mode === 'token-compactor-catalog') {
+    console.log(`Compactors: ${envelope.catalog.compactors.length}; Digest: ${envelope.catalog.catalog_digest}`);
+    for (const compactor of envelope.catalog.compactors) console.log(`- ${compactor.id}: family=${compactor.family}; commands=${compactor.command_names.join(', ')}`);
+  } else if (envelope.mode === 'token-metrics-verify') {
+    console.log(`File: ${envelope.summary.file}; Compactions: ${envelope.summary.compaction_count}; savings=${envelope.summary.savings_ratio}`);
+    console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+    if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+  } else {
+    console.log(`File: ${envelope.summary.file}; Compactor: ${envelope.summary.compactor_id}; savings=${envelope.summary.savings_ratio}`);
+    console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+    if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+  }
+  if (envelope.quality?.length > 0) printList('Blocked reasons', envelope.quality);
+  console.log(`Action: ${envelope.action}`);
+}