@ryuenn3123/agentic-senior-core 4.1.0 → 4.2.1

package/lib/cli/commands/optimize.mjs

@@ -7,6 +7,11 @@ import {
   TOKEN_OPTIMIZATION_REPORT_FILE_NAME,
   normalizeAgentName,
   detectRtkBinary,
+  detectAscxRuntime,
+  checkAscxTeeReadiness,
+  resolveRuntimeTokenSaverMode,
+  buildRuntimeTokenSaverWarnings,
+  buildRuntimeTokenSaverNextAction,
   buildRtkInstallHint,
   buildRtkHookCommand,
   createTokenOptimizationState,
@@ -19,12 +24,43 @@ export function parseOptimizeArguments(commandArguments) {
     targetDirectory: '.',
     agent: 'copilot',
     enabled: true,
+    mode: 'configure',
     show: false,
   };
 
+  function setOptimizeMode(nextMode) {
+    if (parsedOptimizeOptions.mode !== 'configure' && parsedOptimizeOptions.mode !== nextMode) {
+      throw new Error(`Conflicting optimize modes: ${parsedOptimizeOptions.mode} and ${nextMode}`);
+    }
+
+    parsedOptimizeOptions.mode = nextMode;
+  }
+
   for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
     const currentArgument = commandArguments[argumentIndex];
 
+    if (currentArgument === 'install') {
+      setOptimizeMode('install');
+      parsedOptimizeOptions.enabled = true;
+      continue;
+    }
+
+    if (currentArgument === 'off') {
+      setOptimizeMode('off');
+      parsedOptimizeOptions.enabled = false;
+      continue;
+    }
+
+    if (currentArgument === 'status') {
+      setOptimizeMode('status');
+      continue;
+    }
+
+    if (currentArgument === 'doctor') {
+      setOptimizeMode('doctor');
+      continue;
+    }
+
     if (!currentArgument.startsWith('--')) {
       parsedOptimizeOptions.targetDirectory = currentArgument;
       continue;
@@ -43,19 +79,36 @@ export function parseOptimizeArguments(commandArguments) {
 
     if (currentArgument === '--enable') {
       parsedOptimizeOptions.enabled = true;
+      if (parsedOptimizeOptions.mode === 'off') {
+        setOptimizeMode('install');
+      }
       continue;
     }
 
     if (currentArgument === '--disable') {
       parsedOptimizeOptions.enabled = false;
+      if (parsedOptimizeOptions.mode === 'install') {
+        setOptimizeMode('off');
+      }
       continue;
     }
 
     if (currentArgument === '--show') {
+      setOptimizeMode('show');
       parsedOptimizeOptions.show = true;
       continue;
     }
 
+    if (currentArgument === '--status') {
+      setOptimizeMode('status');
+      continue;
+    }
+
+    if (currentArgument === '--doctor') {
+      setOptimizeMode('doctor');
+      continue;
+    }
+
     throw new Error(`Unknown option: ${currentArgument}`);
   }
 
@@ -63,6 +116,78 @@ export function parseOptimizeArguments(commandArguments) {
   return parsedOptimizeOptions;
 }
 
+function formatStatusLine(label, value) {
+  return `${label}: ${value}`;
+}
+
+async function buildRuntimeTokenSaverStatus(resolvedTargetDirectoryPath, options = {}) {
+  const onboardingReport = await loadOnboardingReportIfExists(resolvedTargetDirectoryPath);
+  const existingOptimizationState = await readTokenOptimizationState(resolvedTargetDirectoryPath);
+  const ascxDetection = detectAscxRuntime();
+  const rtkDetection = detectRtkBinary();
+  const teeReadiness = await checkAscxTeeReadiness(resolvedTargetDirectoryPath, {
+    writeProbe: options.writeProbe === true,
+  });
+  const mode = resolveRuntimeTokenSaverMode({
+    tokenOptimizationState: existingOptimizationState,
+    ascxDetection,
+    rtkDetection,
+  });
+  const warnings = buildRuntimeTokenSaverWarnings({
+    mode,
+    onboardingReport,
+    ascxDetection,
+    teeReadiness,
+    rtkDetection,
+  });
+
+  return {
+    targetDirectory: resolvedTargetDirectoryPath,
+    initialized: Boolean(onboardingReport),
+    mode,
+    ascx: ascxDetection,
+    tee: teeReadiness,
+    rtk: rtkDetection,
+    nineRouter: {
+      status: 'not-checked',
+      reason: 'localhost probing is intentionally deferred',
+    },
+    warnings,
+    nextAction: buildRuntimeTokenSaverNextAction({ mode, warnings }),
+    tokenOptimizationState: existingOptimizationState,
+  };
+}
+
+function printRuntimeTokenSaverStatus(statusReport, options = {}) {
+  const title = options.title || 'Runtime token saver status';
+  const ascxStatus = statusReport.ascx.isAvailable
+    ? `found (${statusReport.ascx.source})`
+    : 'missing';
+  const rtkStatus = statusReport.rtk.isAvailable
+    ? `detected${statusReport.rtk.version ? ` (${statusReport.rtk.version})` : ''}`
+    : 'not-detected';
+
+  console.log(title);
+  console.log(formatStatusLine('target', statusReport.targetDirectory));
+  console.log(formatStatusLine('initialized', statusReport.initialized ? 'yes' : 'no'));
+  console.log(formatStatusLine('mode', statusReport.mode));
+  console.log(formatStatusLine('ascx', ascxStatus));
+  console.log(formatStatusLine('tee', `${statusReport.tee.status} (${statusReport.tee.path})`));
+  console.log(formatStatusLine('rtk', rtkStatus));
+  console.log(formatStatusLine('9router', statusReport.nineRouter.status));
+
+  if (statusReport.warnings.length > 0) {
+    console.log('warnings:');
+    for (const warning of statusReport.warnings) {
+      console.log(`- ${warning}`);
+    }
+  } else {
+    console.log('warnings: none');
+  }
+
+  console.log(formatStatusLine('next_action', statusReport.nextAction));
+}
+
 export async function runOptimizeCommand(targetDirectoryArgument, optimizeOptions = {}) {
   const optimizationStartedAt = Date.now();
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
@@ -72,7 +197,23 @@ export async function runOptimizeCommand(targetDirectoryArgument, optimizeOption
   const selectedAgentName = normalizeAgentName(optimizeOptions.agent || 'copilot');
   const rtkDetection = detectRtkBinary();
 
-  if (optimizeOptions.show) {
+  if (optimizeOptions.mode === 'status') {
+    const statusReport = await buildRuntimeTokenSaverStatus(resolvedTargetDirectoryPath);
+    printRuntimeTokenSaverStatus(statusReport);
+    return;
+  }
+
+  if (optimizeOptions.mode === 'doctor') {
+    const statusReport = await buildRuntimeTokenSaverStatus(resolvedTargetDirectoryPath, {
+      writeProbe: true,
+    });
+    printRuntimeTokenSaverStatus(statusReport, {
+      title: 'ASCX runtime token saver doctor',
+    });
+    return;
+  }
+
+  if (optimizeOptions.show || optimizeOptions.mode === 'show') {
     const existingOptimizationState = await readTokenOptimizationState(resolvedTargetDirectoryPath);
     console.log(
       JSON.stringify(
@@ -97,7 +238,7 @@ export async function runOptimizeCommand(targetDirectoryArgument, optimizeOption
   }
 
   const tokenOptimizationState = createTokenOptimizationState({
-    isEnabled: optimizeOptions.enabled,
+    isEnabled: optimizeOptions.mode === 'off' ? false : optimizeOptions.enabled,
     selectedAgentName,
     rtkDetection,
   });

package/lib/cli/commands/upgrade/design-intent-seed.mjs

@@ -0,0 +1,46 @@
+import path from 'node:path';
+
+import { buildDesignIntentSeedFromSignals } from '../../project-scaffolder.mjs';
+
+export function buildUpgradeDesignIntentSeed({
+  targetDirectoryPath,
+  packageManifest,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  uiScopeSignals,
+}) {
+  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim()
+    || 'existing-ui-project';
+  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
+    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
+    || uiScopeSignals.signalReasons.some((signalReason) => {
+      return signalReason.includes('android') || signalReason.includes('ios');
+    });
+  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
+  const projectDescription = String(packageManifest?.description || '').trim()
+    || `Existing ${resolvedDomain.toLowerCase()} detected during upgrade. Create a project-specific dynamic design contract before shipping new UI work.`;
+
+  return buildDesignIntentSeedFromSignals({
+    projectName,
+    projectDescription,
+    primaryDomain: resolvedDomain,
+    features: [],
+    initContext: {
+      stackFileName: selectedStackFileName,
+      blueprintFileName: selectedBlueprintFileName,
+    },
+    status: 'seed-generated-during-upgrade',
+    supplementalFields: {
+      upgradeSignals: {
+        detectedFrom: uiScopeSignals.signalReasons,
+        generatedBy: 'upgrade-seed',
+      },
+      repoEvidence: {
+        uiSignalReasons: uiScopeSignals.signalReasons,
+        frontendMetrics: uiScopeSignals.frontendEvidenceMetrics || null,
+        designEvidenceSummary: uiScopeSignals.designEvidenceSummary || null,
+        workspaceUiEntries: uiScopeSignals.workspaceUiEntries || [],
+      },
+    },
+  });
+}

package/lib/cli/commands/upgrade/token-optimization-state.mjs

@@ -0,0 +1,51 @@
+import {
+  createTokenOptimizationState,
+  detectRtkBinary,
+  normalizeAgentName,
+  readTokenOptimizationState,
+  writeTokenOptimizationState,
+} from '../../token-optimization.mjs';
+
+export async function resolveUpgradeTokenOptimizationPlan(targetDirectoryPath, existingOnboardingReport) {
+  const existingState = await readTokenOptimizationState(targetDirectoryPath);
+  const optedOut = existingOnboardingReport?.tokenOptimization?.enabled === false;
+  const selectedAgentName = normalizeAgentName(
+    existingOnboardingReport?.tokenOptimization?.selectedAgent || 'copilot'
+  );
+
+  return {
+    existingState,
+    optedOut,
+    selectedAgentName,
+    shouldSeed: !existingState && !optedOut,
+    previewLabel: optedOut
+      ? 'disabled (preserved opt-out)'
+      : existingState
+        ? 'enabled'
+        : 'enabled (will seed missing ASCX state)',
+    reportState: existingState
+      || (optedOut ? existingOnboardingReport?.tokenOptimization || { enabled: false } : null),
+  };
+}
+
+export async function applyUpgradeTokenOptimizationPlan(targetDirectoryPath, plan) {
+  if (!plan.shouldSeed) {
+    return {
+      createdFileName: null,
+      reportState: plan.reportState,
+    };
+  }
+
+  const tokenOptimizationState = createTokenOptimizationState({
+    isEnabled: true,
+    selectedAgentName: plan.selectedAgentName,
+    rtkDetection: detectRtkBinary(),
+  });
+
+  await writeTokenOptimizationState(targetDirectoryPath, tokenOptimizationState);
+
+  return {
+    createdFileName: '.agent-context/state/token-optimization.json',
+    reportState: tokenOptimizationState,
+  };
+}

package/lib/cli/commands/upgrade.mjs

@@ -39,15 +39,21 @@ import {
 } from '../compiler.mjs';
 
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
-import { performRollback } from '../rollback.mjs';
 import {
-  detectProjectDocTemplateStaleness,
-  buildDesignIntentSeedFromSignals,
-} from '../project-scaffolder.mjs';
+  createBackup,
+  ensureBackupGitignoreEntry,
+  ensureRuntimeArtifactGitignoreEntries,
+} from '../backup.mjs';
+import { performRollback } from '../rollback.mjs';
+import { detectProjectDocTemplateStaleness } from '../project-scaffolder.mjs';
 import { migrateExistingDesignIntentToResearchDossierSchema } from '../project-scaffolder/design-contract/research-dossier-migration.mjs';
 import { ensureActiveMemorySnapshot } from '../memory-continuity.mjs';
 import { buildExistingProjectMajorConstraints } from '../init-detection-flow.mjs';
+import { buildUpgradeDesignIntentSeed } from './upgrade/design-intent-seed.mjs';
+import {
+  applyUpgradeTokenOptimizationPlan,
+  resolveUpgradeTokenOptimizationPlan,
+} from './upgrade/token-optimization-state.mjs';
 
 export function parseUpgradeArguments(commandArguments) {
   const parsedUpgradeOptions = {
@@ -102,46 +108,6 @@ export function parseUpgradeArguments(commandArguments) {
   return parsedUpgradeOptions;
 }
 
-function buildUpgradeDesignIntentSeed({
-  targetDirectoryPath,
-  packageManifest,
-  selectedStackFileName,
-  selectedBlueprintFileName,
-  uiScopeSignals,
-}) {
-  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim() || 'existing-ui-project';
-  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
-    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
-    || uiScopeSignals.signalReasons.some((signalReason) => signalReason.includes('android') || signalReason.includes('ios'));
-  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
-  const projectDescription = String(packageManifest?.description || '').trim()
-    || `Existing ${resolvedDomain.toLowerCase()} detected during upgrade. Create a project-specific dynamic design contract before shipping new UI work.`;
-
-  return buildDesignIntentSeedFromSignals({
-    projectName,
-    projectDescription,
-    primaryDomain: resolvedDomain,
-    features: [],
-    initContext: {
-      stackFileName: selectedStackFileName,
-      blueprintFileName: selectedBlueprintFileName,
-    },
-    status: 'seed-generated-during-upgrade',
-    supplementalFields: {
-      upgradeSignals: {
-        detectedFrom: uiScopeSignals.signalReasons,
-        generatedBy: 'upgrade-seed',
-      },
-      repoEvidence: {
-        uiSignalReasons: uiScopeSignals.signalReasons,
-        frontendMetrics: uiScopeSignals.frontendEvidenceMetrics || null,
-        designEvidenceSummary: uiScopeSignals.designEvidenceSummary || null,
-        workspaceUiEntries: uiScopeSignals.workspaceUiEntries || [],
-      },
-    },
-  });
-}
-
 export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
 
@@ -175,6 +141,10 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     const stackFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'stacks'));
     const blueprintFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'blueprints'));
     const existingOnboardingReport = await loadOnboardingReportIfExists(resolvedTargetDirectoryPath);
+    const tokenOptimizationPlan = await resolveUpgradeTokenOptimizationPlan(
+      resolvedTargetDirectoryPath,
+      existingOnboardingReport
+    );
     const projectDetection = await detectProjectContext(resolvedTargetDirectoryPath);
     const selectedProfileName = PROFILE_PRESETS[existingOnboardingReport?.selectedProfile]
       ? existingOnboardingReport.selectedProfile
@@ -302,6 +272,9 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     }
     console.log(`- CI/CD quality checks (guardrails): ${includeCiGuardrails ? 'enabled' : 'disabled'}`);
     console.log('- Instruction surface: AGENTS.md canonical with CLAUDE.md and GEMINI.md import bridges');
+    console.log('- Default activation cues: Adaptive Context bootstrap, ASCX wrappers, Compact Natural replies');
+    console.log(`- Token optimization policy: ${tokenOptimizationPlan.previewLabel}`);
+    console.log('- Default response mode: Compact Natural Mode enabled');
     console.log(`- Managed surface stale files: ${managedSurfacePlan.staleFiles.length}`);
     console.log(`- Managed surface stale directories: ${managedSurfacePlan.staleDirectories.length}`);
     console.log(`- Managed surface sync mode: 1:1 (prune enabled)`);
@@ -373,6 +346,12 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     if (backupGitignoreResult.status !== 'unchanged') {
       console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
     }
+    const runtimeArtifactGitignoreResult = await ensureRuntimeArtifactGitignoreEntries(resolvedTargetDirectoryPath);
+    if (runtimeArtifactGitignoreResult.status !== 'unchanged') {
+      console.log(
+        `Local runtime artifacts ignored in .gitignore (${runtimeArtifactGitignoreResult.addedEntries.join(', ')}).`
+      );
+    }
 
     try {
       const governanceSyncResult = await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
@@ -382,6 +361,13 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       });
       const supplementalCreatedFileNames = [];
       const shouldEnsureActiveMemorySnapshot = existingOnboardingReport?.memoryContinuity?.enabled !== false;
+      const tokenOptimizationApplyResult = await applyUpgradeTokenOptimizationPlan(
+        resolvedTargetDirectoryPath,
+        tokenOptimizationPlan
+      );
+      if (tokenOptimizationApplyResult.createdFileName) {
+        supplementalCreatedFileNames.push(tokenOptimizationApplyResult.createdFileName);
+      }
 
       if (shouldSeedDesignIntentOnApply && designIntentSeedContent) {
         const docsDirectoryPath = path.join(resolvedTargetDirectoryPath, 'docs');
@@ -427,6 +413,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         projectDetection,
         runtimeEnvironment: existingOnboardingReport?.runtimeEnvironment || null,
         operationMode: 'upgrade',
+        tokenOptimization: tokenOptimizationApplyResult.reportState,
         detectionTransparency,
         uiScopeSignals,
       });
@@ -464,6 +451,8 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       }
 
       console.log('\nRefreshed files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
+      console.log('Default activation cues remain Adaptive Context bootstrap, ASCX command wrappers, and Compact Natural final replies.');
+      console.log('Default response mode remains Compact Natural Mode through .agent-context/prompts/compact-natural-mode.md.');
       console.log('\nNext-step suggestion (UI scope): run `npx @ryuenn3123/agentic-senior-core audit:design-anti-repeat` to scan CSS, SCSS, SASS, LESS, Tailwind config, and design-token files in this project for typography or palette values that match the anti-repeat ledger in docs/design-intent.json. Add it to your CI alongside `npm test` once the design dossier is populated.');
     } catch (error) {
       console.error('\n[FATAL] An error occurred during upgrade. Attempting automatic rollback...');

package/lib/cli/compiler.mjs

@@ -202,6 +202,14 @@ export async function writeOnboardingReport({
     containerizationStrategy: buildContainerizationStrategySnapshot(dockerStrategy),
     tokenOptimization: resolvedTokenOptimization,
     memoryContinuity: resolvedMemoryContinuity,
+    responseCompression: {
+      enabled: true,
+      mode: 'compact-natural-mode',
+      defaultOn: true,
+      promptFile: '.agent-context/prompts/compact-natural-mode.md',
+      appliesTo: 'agent-final-responses',
+      commandOutputBoundary: 'ASCX handles command-output compression separately',
+    },
     autoDetection: {
       detectedStack: projectDetection.detectedStackFileName,
       detectedAdditionalStacks: projectDetection.secondaryStackFileNames || [],
@@ -383,6 +391,7 @@ export async function buildCompiledRulesContent({
     [
       '## LAYER 5: EXECUTION PROMPTS AND UI TRIGGERS',
       'Load these prompt contracts only when their trigger matches the user request:',
+      'Default. .agent-context/prompts/compact-natural-mode.md -> final response shape and evidence-preserving compact prose',
       '0. Documentation-first mode -> docs, documentation, dokumen, docs/*, architecture docs, flow docs, API docs, lengkapkan docs',
       '1. .agent-context/prompts/init-project.md -> create, build, new project, scaffold',
       '2. .agent-context/prompts/refactor.md -> refactor, improve, clean up, fix',

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -31,6 +31,7 @@ function buildDockerStrategyExecutionBlock(dockerStrategy) {
     '- Required asset floor: ' + requiredAssetFloor + '.',
     '- Keep development and production lanes separate when both are selected.',
     '- If the user asks to create files without commands, write the files and documented commands, but do not execute Docker build, Compose, or registry commands.',
+    '- If Docker is enabled for development, local development setup and first-build instructions in the README must use Docker (e.g., `docker compose up`) rather than fallback local commands like `npm run dev`.',
   ];
 }
 

package/lib/cli/token-optimization.mjs

@@ -1,8 +1,10 @@
+import { existsSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { platform } from 'node:process';
 
+import { REPOSITORY_ROOT } from './constants.mjs';
 import { pathExists } from './utils.mjs';
 
 export const TOKEN_OPTIMIZATION_STATE_FILE_NAME = 'token-optimization.json';
@@ -44,13 +46,13 @@ const COMMAND_REWRITE_MAPPINGS = [
   },
   {
     rawCommand: 'git status',
-    optimizedCommand: 'rtk git status',
-    reason: 'Status output is condensed to actionable file changes.',
+    optimizedCommand: 'ascx git status',
+    reason: 'ASCX condenses status output while preserving changed-file evidence and raw tee safety.',
   },
   {
     rawCommand: 'git diff',
-    optimizedCommand: 'rtk git diff',
-    reason: 'Diff noise is trimmed while preserving code-review context.',
+    optimizedCommand: 'ascx git diff',
+    reason: 'ASCX preserves changed files, hunk anchors, binary/deleted markers, truncation notes, and raw tee safety.',
   },
   {
     rawCommand: 'git log -n 10',
@@ -59,8 +61,8 @@ const COMMAND_REWRITE_MAPPINGS = [
   },
   {
     rawCommand: 'npm test',
-    optimizedCommand: 'rtk test npm test',
-    reason: 'Test results emphasize failures and suppress repetitive pass logs.',
+    optimizedCommand: 'ascx npm test',
+    reason: 'ASCX preserves exit code, failing tests, assertions, file paths, and raw tee safety.',
   },
   {
     rawCommand: 'npm run build',
@@ -179,6 +181,157 @@ export function detectRtkBinary() {
   }
 }
 
+export function detectAscxRuntime() {
+  const localBinPath = path.join(REPOSITORY_ROOT, 'bin', 'ascx.js');
+  const pathDetection = spawnSync('ascx', [], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const pathBinaryLooksAvailable = pathDetection.error == null
+    && typeof pathDetection.status === 'number'
+    && /command is required/i.test(`${pathDetection.stdout || ''}\n${pathDetection.stderr || ''}`);
+
+  if (pathBinaryLooksAvailable) {
+    return {
+      isAvailable: true,
+      source: 'path',
+      command: 'ascx',
+      localBinPath,
+      detectionError: null,
+    };
+  }
+
+  if (existsSync(localBinPath)) {
+    return {
+      isAvailable: true,
+      source: 'package-bin',
+      command: `node ${localBinPath}`,
+      localBinPath,
+      detectionError: pathDetection.error ? pathDetection.error.message : null,
+    };
+  }
+
+  return {
+    isAvailable: false,
+    source: 'missing',
+    command: null,
+    localBinPath,
+    detectionError: pathDetection.error
+      ? pathDetection.error.message
+      : (pathDetection.stderr || pathDetection.stdout || 'ascx binary was not detected').trim(),
+  };
+}
+
+export async function checkAscxTeeReadiness(targetDirectoryPath, options = {}) {
+  const shouldWriteProbe = options.writeProbe === true;
+  const stateDirectoryPath = path.join(targetDirectoryPath, '.agent-context', 'state');
+  const teeDirectoryPath = path.join(stateDirectoryPath, 'token-saver', 'tee');
+
+  try {
+    if (shouldWriteProbe) {
+      await fs.mkdir(teeDirectoryPath, { recursive: true });
+      const probeFilePath = path.join(teeDirectoryPath, `.ascx-probe-${process.pid}.tmp`);
+      await fs.writeFile(probeFilePath, 'ascx tee probe\n', 'utf8');
+      await fs.rm(probeFilePath, { force: true });
+    } else {
+      await fs.access(stateDirectoryPath);
+    }
+
+    return {
+      status: 'writable',
+      path: teeDirectoryPath,
+      error: null,
+    };
+  } catch (readinessError) {
+    return {
+      status: 'not-writable',
+      path: teeDirectoryPath,
+      error: readinessError instanceof Error ? readinessError.message : String(readinessError),
+    };
+  }
+}
+
+export function resolveRuntimeTokenSaverMode({
+  tokenOptimizationState,
+  ascxDetection,
+  rtkDetection,
+}) {
+  const stateEnabled = tokenOptimizationState?.enabled === true;
+  const rtkDetected = rtkDetection?.isAvailable === true;
+
+  if (stateEnabled && ascxDetection?.isAvailable && rtkDetected) {
+    return 'conflict-risk';
+  }
+
+  if (stateEnabled && ascxDetection?.isAvailable) {
+    return 'runtime-on';
+  }
+
+  if (stateEnabled) {
+    return 'policy-only';
+  }
+
+  if (rtkDetected) {
+    return 'external-runtime-detected';
+  }
+
+  return 'runtime-off';
+}
+
+export function buildRuntimeTokenSaverWarnings({
+  mode,
+  onboardingReport,
+  ascxDetection,
+  teeReadiness,
+  rtkDetection,
+}) {
+  const warnings = [];
+
+  if (!onboardingReport) {
+    warnings.push('project is not initialized; run init before enabling runtime token saving');
+  }
+
+  if (!ascxDetection?.isAvailable) {
+    warnings.push('ascx binary is missing; supported commands will not be compressed');
+  }
+
+  if (teeReadiness?.status !== 'writable') {
+    warnings.push('raw tee folder is not writable; failing commands may lose safety logs');
+  }
+
+  if (mode === 'conflict-risk') {
+    warnings.push('ASCX and an external runtime compressor both appear active; avoid double compression');
+  } else if (rtkDetection?.isAvailable) {
+    warnings.push('external runtime compressor detected; keep only one runtime compressor enabled by default');
+  }
+
+  return warnings;
+}
+
+export function buildRuntimeTokenSaverNextAction({ mode, warnings }) {
+  if (warnings.some((warning) => warning.includes('not initialized'))) {
+    return 'Run agentic-senior-core init before enabling ASCX runtime saving.';
+  }
+
+  if (warnings.some((warning) => warning.includes('tee folder'))) {
+    return 'Fix .agent-context/state write access, then rerun optimize doctor.';
+  }
+
+  if (mode === 'conflict-risk') {
+    return 'Disable either ASCX runtime saving or the external compressor before using compressed command output.';
+  }
+
+  if (mode === 'runtime-on') {
+    return 'Use ascx git status, ascx git diff, and ascx npm test for supported high-volume command output.';
+  }
+
+  if (mode === 'policy-only') {
+    return 'Install or expose the ascx binary, then rerun optimize doctor.';
+  }
+
+  return 'Run agentic-senior-core optimize install to enable ASCX guidance for this repository.';
+}
+
 export function buildRtkInstallHint() {
   if (platform === 'win32') {
     return 'Install the external token optimizer binary for Windows, extract it, and ensure the executable is on PATH.';
@@ -298,6 +451,7 @@ export function buildTokenOptimizationGuidanceBlock(tokenOptimizationState) {
   );
 
   const fallbackGuidance = [
+    '- Use ascx git status, ascx git diff, and ascx npm test when the ascx binary is available.',
     '- Use command variants with bounded output such as git diff --stat, rg --max-count, and npm test -- --reporter=dot.',
     '- Request only the lines or sections required for the current decision.',
     '- If shell output is still large, summarize and continue iteratively instead of dumping full logs.',
@@ -319,6 +473,7 @@ export function buildTokenOptimizationGuidanceBlock(tokenOptimizationState) {
     ...rewriteLines,
     '',
     'Important scope note:',
+    '- ASCX wrappers are explicit local command wrappers, not provider gateways.',
     '- Shell rewrite hooks affect shell tool calls only.',
     '- Built-in read/grep/glob style tools may bypass shell rewrites, so explicit compact shell commands should be preferred in high-volume sessions.',
     '',