@planu/cli 4.4.3 → 4.6.0

package/dist/engine/token-optimizer/output-filter.js

@@ -0,0 +1,67 @@
+function escapeInert(text) {
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function redact(text, patterns) {
+    return patterns.reduce((current, pattern) => {
+        const re = new RegExp(pattern, 'gi');
+        return current.replace(re, '[redacted]');
+    }, text);
+}
+function uniqueLines(lines) {
+    return [...new Set(lines)];
+}
+function failureLines(lines) {
+    const failures = lines.filter((line) => /\b(error|fail|failed|exception|critical)\b/i.test(line));
+    return failures.length > 0 ? failures : lines;
+}
+function jsonSummary(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return [`JSON object keys: ${Object.keys(parsed).join(', ')}`];
+        }
+        if (Array.isArray(parsed)) {
+            return [`JSON array length: ${String(parsed.length)}`];
+        }
+    }
+    catch {
+        // Fall through to normal line handling.
+    }
+    return text.split('\n');
+}
+function selectStrategy(input) {
+    const strategy = input.policy.outputs.strategies[input.kind] ?? input.policy.outputs.strategies.generic;
+    if (strategy === undefined) {
+        throw new Error('Token waste policy must define outputs.strategies.generic');
+    }
+    return strategy;
+}
+function compactLines(input, strategy) {
+    const rawLines = strategy.summarizeKeys === true ? jsonSummary(input.text) : input.text.split('\n');
+    const selected = strategy.keepFailures === true ? failureLines(rawLines) : rawLines;
+    const unique = strategy.uniqueOnly === true ? uniqueLines(selected) : selected;
+    return unique.slice(0, strategy.maxLines);
+}
+export function filterVerboseOutput(input) {
+    const strategy = selectStrategy(input);
+    const originalLines = input.text.split('\n').length;
+    const lines = compactLines(input, strategy);
+    const compact = redact(escapeInert(lines.join('\n')), input.policy.redaction.redactPatterns);
+    const decisions = [
+        {
+            decision: originalLines > lines.length ? 'summarize' : 'include',
+            target: input.kind,
+            reason: `Applied policy output strategy for ${input.kind}.`,
+            evidence: [{ source: 'policy', key: `outputs.strategies.${input.kind}` }],
+            confidence: input.policy.outputs.strategies[input.kind] !== undefined ? 'high' : 'medium',
+        },
+    ];
+    return {
+        text: compact,
+        originalLines,
+        returnedLines: lines.length,
+        ...(input.fullOutputRef !== undefined ? { fullOutputRef: input.fullOutputRef } : {}),
+        decisions,
+    };
+}
+//# sourceMappingURL=output-filter.js.map

package/dist/engine/token-optimizer/policy-loader.d.ts

@@ -0,0 +1,3 @@
+import type { LoadedTokenWastePolicy, TokenWastePolicyLoadOptions } from '../../types/token-waste-autopilot.js';
+export declare function loadTokenWastePolicy(projectPath?: string, options?: TokenWastePolicyLoadOptions): Promise<LoadedTokenWastePolicy>;
+//# sourceMappingURL=policy-loader.d.ts.map

package/dist/engine/token-optimizer/policy-loader.js

@@ -0,0 +1,83 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function configPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), '../../config/token-waste-autopilot.json');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mergeDeep(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const current = result[key];
+        result[key] = isRecord(current) && isRecord(value) ? mergeDeep(current, value) : value;
+    }
+    return result;
+}
+function assertStringArray(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`Invalid token waste policy at ${path}: expected string[]`);
+    }
+}
+function validatePolicy(value) {
+    if (!isRecord(value)) {
+        throw new Error('Invalid token waste policy: expected object');
+    }
+    if (value.version !== 1) {
+        throw new Error('Invalid token waste policy: version must be 1');
+    }
+    const policy = value;
+    assertStringArray(policy.context.generatedPatterns, 'context.generatedPatterns');
+    assertStringArray(policy.context.stalePatterns, 'context.stalePatterns');
+    assertStringArray(policy.context.summarizePatterns, 'context.summarizePatterns');
+    if (!Number.isFinite(policy.context.staleSessionMinutes) ||
+        policy.context.staleSessionMinutes < 1) {
+        throw new Error('Invalid token waste policy at context.staleSessionMinutes: expected positive number');
+    }
+    assertStringArray(policy.context.safetyOverrideActions, 'context.safetyOverrideActions');
+    if (!isRecord(policy.outputs.strategies)) {
+        throw new Error('Invalid token waste policy at outputs.strategies: expected object');
+    }
+    if (!isRecord(policy.tools.groups)) {
+        throw new Error('Invalid token waste policy at tools.groups: expected object');
+    }
+    for (const [group, tools] of Object.entries(policy.tools.groups)) {
+        assertStringArray(tools, `tools.groups.${group}`);
+    }
+    if (!Number.isFinite(policy.tools.maxRecommended) || policy.tools.maxRecommended < 1) {
+        throw new Error('Invalid token waste policy at tools.maxRecommended: expected positive number');
+    }
+    if (!isRecord(policy.loops.thresholds)) {
+        throw new Error('Invalid token waste policy at loops.thresholds: expected object');
+    }
+    assertStringArray(policy.loops.safetyOverrideActions, 'loops.safetyOverrideActions');
+    assertStringArray(policy.redaction.redactPatterns, 'redaction.redactPatterns');
+    return policy;
+}
+async function readJson(path) {
+    return JSON.parse(await readFile(path, 'utf-8'));
+}
+export async function loadTokenWastePolicy(projectPath, options = {}) {
+    const defaultPolicyPath = options.defaultPolicyPath ?? configPath();
+    const defaultPolicy = validatePolicy(await readJson(defaultPolicyPath));
+    const evidence = [
+        { source: 'policy', key: defaultPolicyPath },
+    ];
+    let merged = defaultPolicy;
+    if (projectPath !== undefined) {
+        const planuConfigPath = join(projectPath, 'planu.json');
+        try {
+            const config = await readJson(planuConfigPath);
+            if (isRecord(config) && isRecord(config.tokenWasteAutopilot)) {
+                merged = validatePolicy(mergeDeep(defaultPolicy, config.tokenWasteAutopilot));
+                evidence.push({ source: 'project-config', key: 'planu.json.tokenWasteAutopilot' });
+            }
+        }
+        catch {
+            // Missing or malformed project config does not block default policy loading.
+        }
+    }
+    return { policy: merged, evidence };
+}
+//# sourceMappingURL=policy-loader.js.map

package/dist/engine/token-optimizer/tool-relevance.d.ts

@@ -0,0 +1,6 @@
+import type { TokenWastePolicy, ToolRelevanceInput, ToolRelevanceResult } from '../../types/token-waste-autopilot.js';
+export declare function toolsFromPolicyGroups(policy: TokenWastePolicy): {
+    name: string;
+}[];
+export declare function recommendRelevantTools(input: ToolRelevanceInput): ToolRelevanceResult;
+//# sourceMappingURL=tool-relevance.d.ts.map

package/dist/engine/token-optimizer/tool-relevance.js

@@ -0,0 +1,57 @@
+function normalized(text) {
+    return text.toLowerCase();
+}
+function matchesIntent(tool, signals) {
+    const haystack = normalized(`${tool.name} ${tool.description ?? ''}`);
+    return signals.some((signal) => haystack.includes(normalized(signal)));
+}
+function groupNamesForTool(toolName, groups) {
+    return Object.entries(groups)
+        .filter(([, tools]) => tools.includes(toolName))
+        .map(([group]) => group);
+}
+export function toolsFromPolicyGroups(policy) {
+    return [...new Set(Object.values(policy.tools.groups).flat())].map((name) => ({ name }));
+}
+export function recommendRelevantTools(input) {
+    const unsupported = new Set(input.hostUnsupportedTools ?? []);
+    const actionSignals = [input.action, ...input.intentSignals].map(normalized);
+    const recommended = [];
+    const avoided = [];
+    for (const tool of input.tools) {
+        const groups = groupNamesForTool(tool.name, input.policy.tools.groups);
+        const isUnsupported = unsupported.has(tool.name);
+        const isRelevant = !isUnsupported &&
+            (matchesIntent(tool, actionSignals) ||
+                groups.some((group) => actionSignals.includes(normalized(group))));
+        if (isRelevant && recommended.length < input.policy.tools.maxRecommended) {
+            recommended.push({
+                decision: 'recommend',
+                target: tool.name,
+                reason: 'Tool matches the current action, intent signals, or policy tool group.',
+                evidence: [
+                    { source: 'policy', key: 'tools.groups', value: groups.join(',') },
+                    { source: 'runtime', key: 'intentSignals', value: input.intentSignals.join(',') },
+                ],
+                confidence: groups.length > 0 ? 'high' : 'medium',
+            });
+            continue;
+        }
+        avoided.push({
+            decision: 'avoid',
+            target: tool.name,
+            reason: isUnsupported
+                ? 'Host capability marks this tool unsupported.'
+                : 'Tool does not match the current action or intent and can add avoidable tool metadata overhead.',
+            evidence: [
+                {
+                    source: isUnsupported ? 'host-capability' : 'policy',
+                    key: isUnsupported ? 'unsupportedTools' : 'tools.groups',
+                },
+            ],
+            confidence: isUnsupported ? 'high' : 'medium',
+        });
+    }
+    return { recommended, avoided };
+}
+//# sourceMappingURL=tool-relevance.js.map

package/dist/tools/create-spec/post-creation.d.ts

@@ -1,5 +1,6 @@
-import type { Spec, PostCreationSuggestion, ProjectKnowledge } from '../../types/index.js';
+import type { Spec, PostCreationSuggestion, ProjectKnowledge, TokenWasteReport } from '../../types/index.js';
 export declare function getAsyncAnalysisPath(projectPath: string, specId: string): string;
+export declare function buildInitialTokenWasteMetadata(specId: string, projectPath: string, description: string): Promise<TokenWasteReport | null>;
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export declare function setupGitBranch(projectId: string, specId: string): Promise<{
     branch: string;

package/dist/tools/create-spec/post-creation.js

@@ -12,11 +12,42 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
+import { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../../engine/token-optimizer/index.js';
 const ASYNC_ANALYSIS_HOOK = 'create-spec-async-analysis';
 export function getAsyncAnalysisPath(projectPath, specId) {
     const projectId = hashProjectPath(projectPath);
     return join(projectDataDir(projectId), 'analysis', `${specId}.json`);
 }
+export async function buildInitialTokenWasteMetadata(specId, projectPath, description) {
+    try {
+        const { policy } = await loadTokenWastePolicy(projectPath);
+        if (!policy.enabled) {
+            return null;
+        }
+        const context = analyzeContextPreflight({
+            action: 'create_spec',
+            policy,
+            candidates: [{ path: 'planu/specs', reason: 'New spec workspace metadata.' }],
+            spec: { id: specId },
+        });
+        const tools = recommendRelevantTools({
+            action: 'create_spec',
+            intentSignals: ['spec', ...description.split(/\s+/).slice(0, 12)],
+            tools: toolsFromPolicyGroups(policy),
+            policy,
+        });
+        return buildTokenWasteReport({
+            action: 'create_spec',
+            policy,
+            context,
+            tools,
+            spec: { id: specId },
+        });
+    }
+    catch {
+        return null;
+    }
+}
 /** Auto-setup git branch (non-blocking). Returns branch info or undefined. */
 export async function setupGitBranch(projectId, specId) {
     const result = await tryAutoSetupGit(projectId, specId);
@@ -182,6 +213,7 @@ export function runAutopilotAsync(specId, projectPath, _description) {
                 specId,
                 completedAt: new Date().toISOString(),
                 pendingAnalysis: false,
+                tokenWasteAutopilot: await buildInitialTokenWasteMetadata(specId, projectPath, _description),
             };
             const analysisPath = getAsyncAnalysisPath(projectPath, specId);
             await mkdir(dirname(analysisPath), { recursive: true });

package/dist/tools/create-spec/question-generator.d.ts

@@ -1,4 +1,4 @@
 import type { InteractiveQuestion, ProjectKnowledge } from '../../types/index.js';
-/** Generate clarification questions based on description gaps and project context. */
+/** Generate clarification questions based on request-specific missing decisions. */
 export declare function generateInteractiveQuestions(description: string, knowledge: ProjectKnowledge | null): InteractiveQuestion[];
 //# sourceMappingURL=question-generator.d.ts.map

package/dist/tools/create-spec/question-generator.js

@@ -1,101 +1,25 @@
-// tools/create-spec/question-generator.ts — SPEC-463 / SPEC-619 / SPEC-624
-// Config-driven interactive question generation with answer pre-extraction.
-import { t } from '../../i18n/index.js';
+// tools/create-spec/question-generator.ts — SPEC-1083
+// Dynamic clarification questions grounded in the user's requested work.
 import { extractSignals } from '../../engine/elicitation/answer-extractor.js';
-import { buildTargetOptions, buildPaymentProviderOptions, buildBillingModelOptions, buildScopeOptions, buildDatabaseOptions, buildUiTypeOptions, } from '../../engine/elicitation/option-builder.js';
-import dimensionsConfig from '../../config/elicitation-dimensions.json' with { type: 'json' };
-const MAX_QUESTIONS = 4;
-const DIMENSIONS = dimensionsConfig;
-/** Generate clarification questions based on description gaps and project context. */
+import { detectDecisionGaps } from '../../engine/elicitation/decision-gap-detector.js';
+import { validateQuestionGrounding } from '../../engine/elicitation/question-grounding-gate.js';
+/** Generate clarification questions based on request-specific missing decisions. */
 export function generateInteractiveQuestions(description, knowledge) {
     const signals = extractSignals(description);
-    const questions = [];
-    for (const dim of DIMENSIONS) {
-        if (questions.length >= MAX_QUESTIONS) {
-            break;
-        }
-        if (!shouldInclude(dim, signals, knowledge)) {
-            continue;
-        }
-        questions.push({
-            question: t(dim.questionKey),
-            header: t(dim.headerKey),
-            options: buildOptions(dim.optionSet, knowledge),
-            multiSelect: dim.multiSelect,
-        });
-    }
-    return questions;
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function isSuppressed(key, signals) {
-    if (key === 'hasTarget') {
-        return signals.hasTarget;
-    }
-    if (key === 'hasScope') {
-        return signals.hasScope;
-    }
-    if (key === 'namedProvider') {
-        return signals.namedProvider !== null;
-    }
-    return false;
-}
-function hasRequiredSignal(key, signals) {
-    if (key === 'hasBilling') {
-        return signals.hasBilling;
-    }
-    if (key === 'hasDatabase') {
-        return signals.hasDatabase;
-    }
-    if (key === 'hasUi') {
-        return signals.hasUi;
-    }
-    if (key === 'hasTarget') {
-        return signals.hasTarget;
-    }
-    if (key === 'hasScope') {
-        return signals.hasScope;
-    }
-    return false;
-}
-function matchesDNA(required, knowledge) {
-    if (!knowledge) {
-        return false;
-    }
-    const database = knowledge.database;
-    const stack = knowledge.stack;
-    const framework = knowledge.framework ?? '';
-    return required.some((r) => database === r || framework === r || stack.includes(r));
-}
-function shouldInclude(dim, signals, knowledge) {
-    if (dim.suppressWhen !== undefined && isSuppressed(dim.suppressWhen, signals)) {
-        return false;
-    }
-    if (dim.requiresSignal !== undefined && !hasRequiredSignal(dim.requiresSignal, signals)) {
-        return false;
-    }
-    if (dim.requiresDNA !== undefined) {
-        return matchesDNA(dim.requiresDNA, knowledge);
-    }
-    return true;
-}
-function buildOptions(optionSet, knowledge) {
-    switch (optionSet) {
-        case 'target':
-            return buildTargetOptions();
-        case 'payment_provider':
-            return buildPaymentProviderOptions(knowledge);
-        case 'billing_model':
-            return buildBillingModelOptions();
-        case 'scope':
-            return buildScopeOptions();
-        case 'database':
-            return buildDatabaseOptions();
-        case 'uiType':
-            return buildUiTypeOptions();
-        default:
-            return [];
-    }
+    const gaps = detectDecisionGaps(signals, knowledge);
+    return gaps.flatMap((gap) => {
+        const question = {
+            question: gap.question,
+            header: gap.header,
+            options: gap.options,
+            multiSelect: gap.multiSelect,
+        };
+        return validateQuestionGrounding(question, {
+            gap,
+            requestText: description,
+        }).passed
+            ? [question]
+            : [];
+    });
 }
 //# sourceMappingURL=question-generator.js.map

package/dist/tools/package-handoff.js

@@ -3,6 +3,7 @@ import { specStore, knowledgeStore } from '../storage/index.js';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { packageHandoff } from '../engine/handoff-packager.js';
 import { detectParadigms } from '../engine/paradigm-detector.js';
+import { analyzeContextPreflight, buildTokenWasteReport, formatTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../engine/token-optimizer/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
 function formatHandoff(pkg) {
@@ -134,6 +135,47 @@ function formatHandoff(pkg) {
     }
     return lines.join('\n');
 }
+async function buildHandoffTokenWasteReport(pkg, knowledge, spec) {
+    try {
+        const { policy } = await loadTokenWastePolicy(knowledge.projectPath);
+        if (!policy.enabled) {
+            return null;
+        }
+        const context = analyzeContextPreflight({
+            action: 'package_handoff',
+            policy,
+            candidates: [...pkg.filesToModify, ...pkg.filesToCreate].map((path) => ({
+                path,
+                reason: 'Referenced by handoff package.',
+            })),
+            spec: {
+                id: spec.id,
+                risk: spec.risk,
+                target: spec.target,
+            },
+        });
+        const tools = recommendRelevantTools({
+            action: 'package_handoff',
+            intentSignals: ['handoff', spec.scope ?? '', spec.target ?? ''].filter(Boolean),
+            tools: toolsFromPolicyGroups(policy),
+            policy,
+        });
+        return buildTokenWasteReport({
+            action: 'package_handoff',
+            policy,
+            context,
+            tools,
+            spec: {
+                id: spec.id,
+                risk: spec.risk,
+                scope: spec.scope,
+            },
+        });
+    }
+    catch {
+        return null;
+    }
+}
 // ── Handler ──────────────────────────────────────────────────────────────────
 export async function handlePackageHandoff(args) {
     const { projectId, specId } = args;
@@ -188,7 +230,10 @@ export async function handlePackageHandoff(args) {
         readinessScore: readinessReport.score,
         constraints: paradigmConstraints,
     };
-    const formatted = formatHandoff(pkgWithScore);
+    const tokenWasteReport = await buildHandoffTokenWasteReport(pkgWithScore, knowledge, spec);
+    const formatted = tokenWasteReport !== null
+        ? `${formatHandoff(pkgWithScore)}\n${formatTokenWasteReport(tokenWasteReport)}`
+        : formatHandoff(pkgWithScore);
     void appendTransitionEvent({
         projectId,
         specId,
@@ -209,6 +254,7 @@ export async function handlePackageHandoff(args) {
             blockers: pkgWithScore.blockers,
             handoffPath: pkgWithScore.handoffPath,
             contextHash: pkgWithScore.contextHash,
+            ...(tokenWasteReport !== null ? { tokenWaste: tokenWasteReport } : {}),
         },
     };
 }

package/dist/tools/schemas/token-intelligence.d.ts

@@ -15,6 +15,7 @@ export declare const TokenIntelligenceViewEnum: z.ZodEnum<{
     summary: "summary";
     budget: "budget";
     detailed: "detailed";
+    autopilot: "autopilot";
     reconciliation: "reconciliation";
     trends: "trends";
 }>;

package/dist/tools/schemas/token-intelligence.js

@@ -9,10 +9,11 @@ export const TokenIntelligenceGroupByEnum = z
     .describe('Group results by: tool (per MCP tool name), model (per AI model), ' +
     'spec (per spec ID), day (daily breakdown)');
 export const TokenIntelligenceViewEnum = z
-    .enum(['summary', 'detailed', 'budget', 'reconciliation', 'trends'])
+    .enum(['summary', 'detailed', 'budget', 'reconciliation', 'trends', 'autopilot'])
     .describe('Dashboard view: summary (high-level overview with top consumers), ' +
     'detailed (full per-tool and per-model breakdown), ' +
     'budget (spending vs monthly limits with projections), ' +
     'reconciliation (estimated vs actual cost accuracy per spec), ' +
-    'trends (usage patterns over time, week-over-week changes, and anomaly alerts)');
+    'trends (usage patterns over time, week-over-week changes, and anomaly alerts), ' +
+    'autopilot (policy-driven recommendations to reduce wasted context, output, and tool usage)');
 //# sourceMappingURL=token-intelligence.js.map

package/dist/tools/status-handler.js

@@ -17,6 +17,7 @@ import { calculateSLAStatus } from '../engine/approval-workflow.js';
 import { readPlanuConfig } from '../engine/planu-config-writer.js';
 import { computePlanuDriftScore } from '../engine/dashboard/drift-score.js';
 import { findStaleBranches, findStaleWorktrees, findStaleStashes, } from '../engine/housekeeping/index.js';
+import { loadTokenWastePolicy } from '../engine/token-optimizer/index.js';
 // SPEC-1011 Bug G: fire-and-forget status.json reconciliation
 import { reconcileStatusFromDisk } from '../engine/status-reconciler/index.js';
 const execFile = promisify(execFileCb);
@@ -127,7 +128,7 @@ function buildSuggestion(snapshot) {
 // Output builder
 // ---------------------------------------------------------------------------
 function buildOutput(params) {
-    const { snapshot, git, ci, slaBreaches, workMode, updateBanner, autoCompleted, sessionTip } = params;
+    const { snapshot, git, ci, slaBreaches, workMode, updateBanner, autoCompleted, sessionTip, tokenWasteHint, } = params;
     const lines = ['Planu Status', '━━━━━━━━━━━━━━━'];
     if (snapshot.active !== null) {
         const title = snapshot.active.title.slice(0, 40);
@@ -162,6 +163,9 @@ function buildOutput(params) {
     if (sessionTip !== undefined) {
         lines.push(`SESSION TIP  ${sessionTip}`);
     }
+    if (tokenWasteHint !== undefined) {
+        lines.push(`TOKEN WASTE ${tokenWasteHint}`);
+    }
     lines.push(`SUGGEST   ${buildSuggestion(snapshot)}`);
     if (workMode !== undefined) {
         lines.push(`WORK MODE ${workMode}`);
@@ -206,7 +210,7 @@ export async function handlePlanStatus(args) {
             /* best-effort */
         });
     }
-    const [snapshot, git, ci, slaBreaches, planuConfig, autoCompleted, sessionState, driftScore, pendingCleanup,] = await Promise.all([
+    const [snapshot, git, ci, slaBreaches, planuConfig, autoCompleted, sessionState, driftScore, pendingCleanup, tokenWastePolicy,] = await Promise.all([
         getStatusSpecSnapshot(projectId),
         getGitState(args.projectPath),
         getCiState(args.projectPath),
@@ -237,6 +241,9 @@ export async function handlePlanStatus(args) {
                 return { branches: 0, worktrees: 0, stashes: 0 };
             }
         })(),
+        loadTokenWastePolicy(args.projectPath)
+            .then((loaded) => loaded.policy)
+            .catch(() => null),
     ]);
     // SPEC-1012: Detect stale release status (best-effort, non-blocking)
     let staleStatusWarnings = [];
@@ -252,6 +259,12 @@ export async function handlePlanStatus(args) {
     const sessionTip = sessionAgeMinutes !== null && sessionAgeMinutes > SESSION_TIP_THRESHOLD_MIN
         ? `Last checkpoint ${String(sessionAgeMinutes)}min ago — run session_handoff then start a fresh session to cut token costs`
         : undefined;
+    const tokenWasteThresholdMin = tokenWastePolicy?.context.staleSessionMinutes;
+    const tokenWasteHint = tokenWasteThresholdMin !== undefined &&
+        sessionAgeMinutes !== null &&
+        sessionAgeMinutes > tokenWasteThresholdMin
+        ? `checkpoint is stale; package or hand off context before continuing`
+        : undefined;
     const workMode = planuConfig?.workMode;
     const updateBanner = consumeUpdateBanner() ?? undefined;
     const text = buildOutput({
@@ -263,6 +276,7 @@ export async function handlePlanStatus(args) {
         updateBanner,
         autoCompleted,
         sessionTip,
+        tokenWasteHint,
     });
     // SPEC-256: Always show /btw hint as educational tip (no context percent available from MCP layer)
     const DEMO_CONTEXT_PERCENT = 65;
@@ -286,6 +300,7 @@ export async function handlePlanStatus(args) {
             lastAuditAt: driftScore?.lastAuditAt ?? null,
             ...(autoCompleted.length > 0 ? { autoCompleted } : {}),
             ...(sessionTip !== undefined ? { sessionTip } : {}),
+            ...(tokenWasteHint !== undefined ? { tokenWasteHint } : {}),
             ...(btwHint !== undefined ? { btw_hint: btwHint } : {}),
             ...(updateBanner !== undefined ? { update_banner: updateBanner } : {}),
             // SPEC-751: pending cleanup counters

package/dist/tools/token-intelligence-handler.js

@@ -1,5 +1,6 @@
 import { getEntries, getAggregation } from '../storage/token-ledger-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
+import { buildTokenWasteReport, detectTokenWasteLoops, formatTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, } from '../engine/token-optimizer/index.js';
 import { join } from 'node:path';
 // ---------------------------------------------------------------------------
 // Constants
@@ -348,6 +349,47 @@ function renderTrends(entries, period) {
     }
     return lines.join('\n');
 }
+async function renderAutopilot(entries, agg, period, projectPath) {
+    const { policy } = await loadTokenWastePolicy(projectPath);
+    if (!policy.enabled) {
+        return [
+            '# Token Intelligence Dashboard — Autopilot View',
+            '',
+            `**Period:** ${periodLabel(period)}`,
+            '',
+            'Token Waste Autopilot is disabled by policy.',
+            '',
+        ].join('\n');
+    }
+    const loops = detectTokenWasteLoops(entries.map((entry) => ({
+        type: 'tool',
+        key: entry.toolName,
+        timestamp: entry.timestamp,
+        changedSincePrevious: false,
+    })), policy, 'token_intelligence');
+    const tools = recommendRelevantTools({
+        action: 'token_intelligence',
+        intentSignals: ['token', 'status', 'budget'],
+        tools: Object.keys(agg.tokensByTool).map((name) => ({ name })),
+        policy,
+    });
+    const report = buildTokenWasteReport({
+        action: 'token_intelligence',
+        policy,
+        loops,
+        tools,
+    });
+    return [
+        '# Token Intelligence Dashboard — Autopilot View',
+        '',
+        `**Period:** ${periodLabel(period)}`,
+        '',
+        `Analyzed ${String(entries.length)} ledger entries across ${String(agg.uniqueTools)} tools.`,
+        '',
+        formatTokenWasteReport(report),
+        '',
+    ].join('\n');
+}
 // ---------------------------------------------------------------------------
 // Empty state
 // ---------------------------------------------------------------------------
@@ -387,7 +429,7 @@ export async function handleTokenIntelligence(input) {
         getEntries(projectHash, dataDir, filter),
         getAggregation(projectHash, dataDir, filter),
     ]);
-    if (entries.length === 0 && view !== 'reconciliation') {
+    if (entries.length === 0 && view !== 'reconciliation' && view !== 'autopilot') {
         return { content: [{ type: 'text', text: renderEmpty(view, period) }] };
     }
     let text;
@@ -404,6 +446,9 @@ export async function handleTokenIntelligence(input) {
         case 'trends':
             text = renderTrends(entries, period);
             break;
+        case 'autopilot':
+            text = await renderAutopilot(entries, agg, period, projectPath);
+            break;
         default:
             text = renderSummary(agg, entries, period, groupBy);
             break;