@moda-ai/cli 1.10.1 → 1.11.0

package/dist/agent-schemas.js

@@ -14,6 +14,7 @@
 //   - ProductionAskResult in ./production-intelligence.ts (production_ask.v0.1)
 //   - ModaIntelligenceV1 in ./intelligence-schema.ts      (moda.intelligence.v1)
 import { MODA_INTELLIGENCE_V1_JSON_SCHEMA } from './intelligence-schema.js';
+import { AGENT_ERROR_CODES } from './output.js';
 const agentSummarySchema = {
     type: 'object',
     additionalProperties: false,
@@ -83,15 +84,54 @@ const agentArtifactSchema = {
         description: { type: 'string' },
     },
 };
+const agentInputRequestSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'question', 'kind'],
+    properties: {
+        id: { type: 'string' },
+        question: { type: 'string' },
+        kind: { type: 'string', enum: ['select', 'confirm', 'text'] },
+        choices: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['value', 'label', 'resume_flags'],
+                properties: {
+                    value: { type: 'string' },
+                    label: { type: 'string' },
+                    resume_flags: { type: 'array', items: { type: 'string' } },
+                },
+            },
+        },
+        resume_command: { type: 'array', items: { type: 'string' } },
+    },
+};
+const agentAuthSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['reason', 'login_command'],
+    properties: {
+        reason: {
+            type: 'string',
+            enum: ['no_stored_credentials', 'token_expired', 'token_revoked', 'renew_failed'],
+        },
+        login_command: { type: 'array', items: { type: 'string' } },
+        resume_command: { type: 'array', items: { type: 'string' } },
+    },
+};
 const agentErrorSchema = {
     type: 'object',
     additionalProperties: false,
     required: ['code', 'message', 'blocking'],
     properties: {
-        code: { type: 'string' },
+        code: { type: 'string', enum: AGENT_ERROR_CODES },
         message: { type: 'string' },
         cause: { type: 'string' },
         suggested_commands: { type: 'array', items: { type: 'string' } },
+        input_request: agentInputRequestSchema,
+        auth: agentAuthSchema,
         blocking: { type: 'boolean' },
     },
 };
@@ -138,7 +178,7 @@ const agentEnvelopeSchema = {
 const agentEventSchema = {
     $id: 'moda.agent_event.v1',
     title: 'AgentEvent',
-    description: 'Streaming NDJSON event emitted in agent-stream mode by the moda CLI.',
+    description: 'Streaming NDJSON event emitted in agent-stream mode by the moda CLI. The first event is started; run_id is constant; seq starts at 1 and increments without gaps; exactly one terminal event (completed, error, cancelled, needs_input, auth_required) ends every stream; heartbeat absence for more than 30 seconds is the stall signal.',
     type: 'object',
     additionalProperties: false,
     required: ['schema_version', 'event', 'command', 'generated_at'],
@@ -146,10 +186,25 @@ const agentEventSchema = {
         schema_version: { type: 'string', const: 'moda.agent_event.v1' },
         event: {
             type: 'string',
-            enum: ['started', 'progress', 'artifact', 'approval_required', 'completed', 'error'],
+            enum: [
+                'started',
+                'progress',
+                'artifact',
+                'approval_required',
+                'completed',
+                'error',
+                'heartbeat',
+                'needs_input',
+                'auth_required',
+                'cancelled',
+                'warning',
+            ],
         },
         command: { type: 'string' },
         generated_at: { type: 'string', format: 'date-time' },
+        run_id: { type: 'string' },
+        seq: { type: 'number' },
+        event_version: { type: 'number' },
         status: { type: 'string', enum: ['ok', 'degraded', 'error'] },
         phase: { type: 'string' },
         message: { type: 'string' },
@@ -157,6 +212,8 @@ const agentEventSchema = {
         artifact: agentArtifactSchema,
         result: agentEnvelopeSchema,
         error: agentErrorSchema,
+        input_request: agentInputRequestSchema,
+        auth: agentAuthSchema,
     },
 };
 const productionEvidenceRefSchema = {

package/dist/auth.js

@@ -3,6 +3,7 @@ import { createServer } from 'node:http';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { resolveModaBaseUrl } from './config.js';
+import { CliAuthError } from './errors.js';
 import { getModaPaths, loadProfileConfig, saveProfileConfig, secretFilePathFromRef, writeSecretJsonFile, } from './profiles.js';
 const CALLBACK_PORT = 8432;
 const AUTH_TIMEOUT_MS = 120_000;
@@ -310,7 +311,10 @@ export async function login(screen = 'login', options = {}) {
 export async function authFetch(path, options = {}, authOptions = {}) {
     const token = loadToken(authOptions);
     if (!token) {
-        throw new Error('Not authenticated. Run "moda init" to log in.');
+        throw new CliAuthError('Not authenticated. Run "moda auth login" to log in.', {
+            reason: 'no_stored_credentials',
+            login_command: ['moda', 'auth', 'login'],
+        });
     }
     const headers = new Headers(options.headers);
     headers.set('Authorization', `Bearer ${token}`);

package/dist/cli.js

@@ -12,16 +12,18 @@ import { runSkillsCommand } from './skills.js';
 import { runHarnessCommand } from './harness.js';
 import { runSyncCommand } from './sync.js';
 import { runDoctorCommand, runStatusCommand } from './doctor.js';
-import { CliInputError } from './errors.js';
+import { CliAuthError, CliCancellationError, CliInputError, CliInputRequiredError, isApiLikeError, isNetworkLikeError } from './errors.js';
 import { buildSearchAdoptionTelemetry, isTelemetryDisabled, SEARCH_MODES, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
 import { isUpdateCheckDisabled, printUpdateNotice, startUpdateCheck, stripUpdateCheckFlag, } from './update-check.js';
 import { createCommandContext } from './command-context.js';
 import { createCommandRegistry } from './command-registry.js';
-import { createAgentErrorEnvelope, errorToAgentError, resolveOutputMode, } from './output.js';
+import { createCliOutput, EXIT_CANCELLED, resolveOutputMode, safeWriteStderr, safeWriteStdout, } from './output.js';
 import { renderJsonSchemas } from './agent-schemas.js';
 import { runAuthCommand, runConfigCommand, runKeysCommand, runProfilesCommand } from './profile-commands.js';
 import { runAgentCommand } from './agent.js';
 import { runProductionCommand } from './production-intelligence.js';
+import { exitCodeForError, finishRun } from './exit-funnel.js';
+import { buildManifest, renderManifestHuman } from './manifest.js';
 export { CliInputError } from './errors.js';
 export function parseArgs(argv) {
     const args = argv.slice(2);
@@ -106,6 +108,7 @@ function printHelp() {
 Commands:
   init                             Set up Moda in your project
   status                           Show concise local Moda setup status
+  manifest                         Describe the CLI machine protocol and commands
   doctor                           Diagnose local Moda setup and data flow
   auth login                       Authenticate with Moda
   auth logout                      Clear cached Moda auth
@@ -136,6 +139,7 @@ Commands:
   sync prompts                     Sync prompt versions to Moda Cloud
   doctor --json                    Emit structured diagnostic checks
   status --json                    Emit concise setup state
+  manifest --json                  Emit the CLI machine protocol manifest
   overview                         Harness health briefing with production signals
   clusters                         Browse topic cluster hierarchy
   cluster-conversations <node_id>  List conversations in a cluster
@@ -228,6 +232,7 @@ Init flags:
 Examples:
   moda init
   moda status
+  moda manifest --json
   moda doctor --json
   moda profiles list
   moda profiles use staging
@@ -377,10 +382,7 @@ function recordConversationsTelemetry(context, data) {
 export async function runCommand(command, positional, flags, positionals = positional ? [positional] : [], context = createCommandContext({ command, positional, positionals, flags })) {
     switch (command) {
         case 'prompts': {
-            await runPromptsCommand(positionals, flags, {
-                profile: context.profile,
-                env: context.env,
-            });
+            await runPromptsCommand(context);
             break;
         }
         case 'overview': {
@@ -713,7 +715,7 @@ export const commandRegistry = createCommandRegistry([
             const result = await runInit(flagsToArgs(context.flags), {
                 onEvent: (event) => {
                     context.output.writeEvent({
-                        event: 'progress',
+                        event: event.status === 'warning' ? 'warning' : 'progress',
                         phase: event.phase,
                         message: event.message,
                         elapsed_ms: Date.now() - context.startedAt,
@@ -726,6 +728,30 @@ export const commandRegistry = createCommandRegistry([
             return { exitCode: 0, apiKey: result.apiKey };
         },
     },
+    {
+        name: 'manifest',
+        description: 'Describe the CLI machine protocol, commands, events, and exit codes',
+        examples: ['moda manifest --json', 'moda --agent manifest'],
+        auth: 'none',
+        outputModes: ['human', 'json', 'agent'],
+        mutability: 'read',
+        validateConfigBeforeRun: false,
+        resetApiRequestCountBeforeRun: false,
+        telemetry: 'none',
+        handler: async (context) => {
+            const manifest = buildManifest(commandRegistry.all());
+            if (context.outputMode === 'human') {
+                if (!context.quiet)
+                    safeWriteStdout(`${renderManifestHuman(manifest)}\n`);
+            }
+            else {
+                context.output.writeData(manifest, {
+                    summary: 'Moda CLI machine protocol manifest.',
+                });
+            }
+            return { exitCode: 0 };
+        },
+    },
     {
         name: 'auth',
         description: 'Authenticate and inspect browser auth sessions',
@@ -1035,55 +1061,58 @@ export const commandRegistry = createCommandRegistry([
         resetApiRequestCountBeforeRun: false,
         telemetry: 'result',
         handler: async (context) => ({
-            exitCode: await runSkillsCommand({
-                command: context.command,
-                positional: context.positional,
-                positionals: context.positionals,
-                flags: context.flags,
-            }),
+            exitCode: await runSkillsCommand(context),
         }),
     },
 ]);
 // --- Main ---
 export function classifyCliError(error) {
-    if (error instanceof z.ZodError || error instanceof CliInputError) {
+    if (error instanceof z.ZodError ||
+        error instanceof CliInputError ||
+        error instanceof CliInputRequiredError ||
+        error instanceof CliAuthError) {
+        // Auth/input-required are caller-actionable states (missing credentials,
+        // needs a choice), not unknown failures. Bucket them with validation so
+        // the missing-API-key case keeps its pre-hardening telemetry type.
         return 'validation_error';
     }
-    if (error instanceof ApiError) {
+    if (error instanceof ApiError || isApiLikeError(error)) {
         return 'api_error';
     }
-    if (error instanceof Error &&
-        (error.message.startsWith('Network error:') ||
-            error.message.startsWith('Request timed out'))) {
+    if (isNetworkLikeError(error)) {
         return 'network_error';
     }
     return 'unknown_error';
 }
 export function printCliError(error) {
     if (error instanceof CliInputError) {
-        console.error(`Error: ${error.message}`);
+        safeWriteStderr(`Error: ${error.message}\n`);
         if (error.usage)
-            console.error(error.usage);
+            safeWriteStderr(`${error.usage}\n`);
     }
     else if (error instanceof z.ZodError) {
         const issues = error.errors.map((e) => {
             const field = e.path.length ? e.path.join('.') : 'input';
             return `  ${field}: ${e.message}`;
         });
-        console.error(`Validation error:\n${issues.join('\n')}`);
+        safeWriteStderr(`Validation error:\n${issues.join('\n')}\n`);
     }
     else if (error instanceof ApiError) {
-        console.error(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}`);
+        safeWriteStderr(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}\n`);
     }
     else if (error instanceof Error) {
-        console.error(`Error: ${error.message}`);
+        safeWriteStderr(`Error: ${error.message}\n`);
     }
     else {
-        console.error('Error:', error);
+        safeWriteStderr(`Error: ${String(error)}\n`);
     }
 }
-function printAgentCliError(command, error) {
-    console.log(JSON.stringify(createAgentErrorEnvelope(command || 'unknown', errorToAgentError(error))));
+function printAgentCliError(command, error, mode = 'agent') {
+    const output = createCliOutput({
+        command: command || 'unknown',
+        mode,
+    });
+    output.writeError(error);
 }
 export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     const { command, flags } = parsed;
@@ -1114,7 +1143,7 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
             env: process.env,
         });
         if (mode === 'agent' || mode === 'agent-stream') {
-            printAgentCliError(command, error);
+            printAgentCliError(command, error, mode);
         }
         else {
             printCliError(error);
@@ -1129,12 +1158,6 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     if (!updateCheckDisabled) {
         void startUpdateCheck();
     }
-    if (definition.validateConfigBeforeRun) {
-        validateConfig();
-    }
-    if (definition.resetApiRequestCountBeforeRun) {
-        resetApiRequestCount();
-    }
     const context = createCommandContext(parsed, {
         commandName: definition.name,
         commandFlags,
@@ -1148,6 +1171,43 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
             env: process.env,
         }),
     });
+    setActiveContext(context);
+    if (definition.validateConfigBeforeRun) {
+        try {
+            validateConfig();
+        }
+        catch (error) {
+            if (!telemetryDisabled && definition.telemetry === 'result-and-error') {
+                void sendCliUsageTelemetry({
+                    apiKey: resolveApiKey(),
+                    command: definition.name,
+                    flags: commandFlags,
+                    status: 'error',
+                    errorType: classifyCliError(error),
+                    exitCode: exitCodeForError(error),
+                    durationMs: Date.now() - startedAt,
+                    apiRequestCount: getApiRequestCount(),
+                    adoption: buildSearchAdoptionTelemetry({
+                        command: definition.name,
+                        positional: parsed.positional,
+                        flags: commandFlags,
+                        outputMode: context.outputMode,
+                        recorded: context.getTelemetryMeta(),
+                        skillVersion: process.env.MODA_SKILL_VERSION,
+                    }),
+                });
+            }
+            if (context.outputMode === 'agent' || context.outputMode === 'agent-stream' || context.outputMode === 'json') {
+                return finishRun(context, { kind: 'error', error });
+            }
+            printCliError(error);
+            context.output.close();
+            return exitCodeForError(error);
+        }
+    }
+    if (definition.resetApiRequestCountBeforeRun) {
+        resetApiRequestCount();
+    }
     try {
         const result = await definition.handler(context);
         if (!telemetryDisabled && definition.telemetry !== 'none') {
@@ -1172,7 +1232,7 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         if (!updateCheckDisabled) {
             printUpdateNotice();
         }
-        return result.exitCode;
+        return finishRun(context, { kind: 'completed', exitCode: result.exitCode });
     }
     catch (error) {
         if (!telemetryDisabled && definition.telemetry === 'result-and-error') {
@@ -1182,7 +1242,7 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
                 flags: commandFlags,
                 status: 'error',
                 errorType: classifyCliError(error),
-                exitCode: 1,
+                exitCode: exitCodeForError(error),
                 durationMs: Date.now() - startedAt,
                 apiRequestCount: getApiRequestCount(),
                 adoption: buildSearchAdoptionTelemetry({
@@ -1195,8 +1255,8 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
                 }),
             });
         }
-        if (context.outputMode === 'agent' || context.outputMode === 'agent-stream') {
-            printAgentCliError(definition.name, error);
+        if (context.outputMode === 'agent' || context.outputMode === 'agent-stream' || context.outputMode === 'json') {
+            return finishRun(context, { kind: 'error', error });
         }
         else {
             printCliError(error);
@@ -1204,9 +1264,34 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         if (!updateCheckDisabled) {
             printUpdateNotice();
         }
-        return 1;
+        context.output.close();
+        return exitCodeForError(error);
     }
 }
+let activeContext;
+let signalCount = 0;
+function setActiveContext(context) {
+    activeContext = context;
+}
+function installSignalHandlers() {
+    const handleSignal = (signal) => {
+        signalCount += 1;
+        if (signalCount > 1) {
+            process.exit(EXIT_CANCELLED);
+        }
+        const reason = `Command cancelled by ${signal}.`;
+        if (activeContext) {
+            void finishRun(activeContext, { kind: 'cancelled', reason }).finally(() => {
+                process.exit(EXIT_CANCELLED);
+            });
+            return;
+        }
+        printCliError(new CliCancellationError(reason));
+        process.exit(EXIT_CANCELLED);
+    };
+    process.once('SIGINT', handleSignal);
+    process.once('SIGTERM', handleSignal);
+}
 async function main() {
     // Set exitCode (don't process.exit) so any in-flight telemetry request
     // can resolve before Node drains its event loop and exits naturally.
@@ -1218,6 +1303,7 @@ import { realpathSync } from 'fs';
 const isMain = process.argv[1] &&
     fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
 if (isMain) {
+    installSignalHandlers();
     main().catch((error) => {
         printCliError(error);
         process.exitCode = 1;

package/dist/config.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { DEFAULT_INGEST_URL, PROD_BASE_URL, getLegacyConfigPath, loadLegacyCliConfig, resolveApiKeyFromActiveProfile, resolveBaseUrl, resolveIngestUrl as resolveProfileIngestUrl, resolveTenantIdFromActiveProfile, syncLegacyConfigToProfile, writeLegacyCliConfig, } from './profiles.js';
+import { CliAuthError } from './errors.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = pkg.version;
 // Canonical host is moda.dev. The www host 308-redirects to the apex, and
@@ -65,9 +66,10 @@ export function resolveModaBaseUrl(options = {}) {
 }
 export function validateConfig() {
     if (!resolveApiKey()) {
-        console.error('Error: no Moda API key found. Set MODA_API_KEY or run "moda init".');
-        console.error('Get your API key from https://moda.dev/settings');
-        process.exit(1);
+        throw new CliAuthError('No Moda API key found. Set MODA_API_KEY or run "moda init".', {
+            reason: 'no_stored_credentials',
+            login_command: ['moda', 'init'],
+        }, 'Get your API key from https://moda.dev/settings');
     }
 }
 // Kept for callers/tests that need the legacy path during migration.

package/dist/errors.d.ts

@@ -2,4 +2,36 @@ export declare class CliInputError extends Error {
     readonly usage?: string | undefined;
     constructor(message: string, usage?: string | undefined);
 }
+export interface AgentInputChoice {
+    value: string;
+    label: string;
+    resume_flags: string[];
+}
+export interface AgentInputRequest {
+    id: string;
+    question: string;
+    kind: 'select' | 'confirm' | 'text';
+    choices?: AgentInputChoice[];
+    resume_command?: string[];
+}
+export interface AgentAuthRequest {
+    reason: 'no_stored_credentials' | 'token_expired' | 'token_revoked' | 'renew_failed';
+    login_command: string[];
+    resume_command?: string[];
+}
+export declare class CliInputRequiredError extends Error {
+    readonly input_request: AgentInputRequest;
+    constructor(message: string, input_request: AgentInputRequest, usage?: string);
+    readonly usage?: string;
+}
+export declare class CliAuthError extends Error {
+    readonly auth: AgentAuthRequest;
+    constructor(message: string, auth: AgentAuthRequest, usage?: string);
+    readonly usage?: string;
+}
+export declare class CliCancellationError extends Error {
+    constructor(message: string);
+}
+export declare function isNetworkLikeError(error: unknown): boolean;
+export declare function isApiLikeError(error: unknown): boolean;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -6,4 +6,44 @@ export class CliInputError extends Error {
         this.name = 'CliInputError';
     }
 }
+export class CliInputRequiredError extends Error {
+    input_request;
+    constructor(message, input_request, usage) {
+        super(message);
+        this.input_request = input_request;
+        this.name = 'CliInputRequiredError';
+        if (usage)
+            this.usage = usage;
+    }
+    usage;
+}
+export class CliAuthError extends Error {
+    auth;
+    constructor(message, auth, usage) {
+        super(message);
+        this.auth = auth;
+        this.name = 'CliAuthError';
+        if (usage)
+            this.usage = usage;
+    }
+    usage;
+}
+export class CliCancellationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliCancellationError';
+    }
+}
+export function isNetworkLikeError(error) {
+    return error instanceof Error &&
+        (error.message.startsWith('Network error:') ||
+            error.message.startsWith('Request timed out') ||
+            error.name === 'AbortError' ||
+            /(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|socket hang up)/i.test(error.message));
+}
+export function isApiLikeError(error) {
+    return error instanceof Error &&
+        (error.name === 'ApiError' ||
+            ('statusCode' in error && typeof error.statusCode === 'number'));
+}
 //# sourceMappingURL=errors.js.map

package/dist/exit-funnel.d.ts

@@ -0,0 +1,14 @@
+import type { CommandContext } from './command-context.js';
+export type RunOutcome = {
+    kind: 'completed';
+    exitCode?: number;
+} | {
+    kind: 'error';
+    error: unknown;
+} | {
+    kind: 'cancelled';
+    reason?: string;
+};
+export declare function finishRun(context: CommandContext, outcome: RunOutcome): Promise<number>;
+export declare function exitCodeForError(error: unknown): number;
+//# sourceMappingURL=exit-funnel.d.ts.map

package/dist/exit-funnel.js

@@ -0,0 +1,49 @@
+import { CliAuthError, CliCancellationError, CliInputRequiredError, } from './errors.js';
+import { EXIT_AUTH_REQUIRED, EXIT_CANCELLED, EXIT_ERROR, EXIT_INPUT_REQUIRED, EXIT_OK, wasOutputCancelled, } from './output.js';
+const finishedContexts = new WeakSet();
+export async function finishRun(context, outcome) {
+    if (finishedContexts.has(context)) {
+        return exitCodeForOutcome(outcome);
+    }
+    finishedContexts.add(context);
+    if (outcome.kind === 'completed') {
+        // Guarantee the stream contract structurally: exactly one terminal event
+        // ends every stream. A handler that returned without writing one gets a
+        // synthetic `completed` (a no-op in non-stream modes and when a terminal
+        // event was already emitted).
+        if (!context.output.hasTerminalOutput()) {
+            context.output.writeEvent({ event: 'completed', status: 'ok' });
+        }
+        context.output.close();
+        if (wasOutputCancelled())
+            return EXIT_CANCELLED;
+        return outcome.exitCode ?? EXIT_OK;
+    }
+    if (outcome.kind === 'cancelled') {
+        context.output.writeCancelled(outcome.reason ?? 'Command cancelled.');
+        context.output.close();
+        return EXIT_CANCELLED;
+    }
+    context.output.writeError(outcome.error);
+    context.output.close();
+    if (wasOutputCancelled())
+        return EXIT_CANCELLED;
+    return exitCodeForError(outcome.error);
+}
+export function exitCodeForError(error) {
+    if (error instanceof CliAuthError)
+        return EXIT_AUTH_REQUIRED;
+    if (error instanceof CliInputRequiredError)
+        return EXIT_INPUT_REQUIRED;
+    if (error instanceof CliCancellationError)
+        return EXIT_CANCELLED;
+    return EXIT_ERROR;
+}
+function exitCodeForOutcome(outcome) {
+    if (outcome.kind === 'completed')
+        return outcome.exitCode ?? EXIT_OK;
+    if (outcome.kind === 'cancelled')
+        return EXIT_CANCELLED;
+    return exitCodeForError(outcome.error);
+}
+//# sourceMappingURL=exit-funnel.js.map

package/dist/harness.js

@@ -7,7 +7,7 @@ import { confirm, select } from '@inquirer/prompts';
 import { callControlAPI } from './api-client.js';
 import { AnalystTui, shouldUseAnalystTui } from './analyst-tui.js';
 import { resolveApiKey, resolveTenantId } from './config.js';
-import { CliInputError } from './errors.js';
+import { CliInputError, CliInputRequiredError } from './errors.js';
 import { getActiveProfile } from './profiles.js';
 import { approveHarnessReport, createHarnessReport, graphForReport, hashHarnessReport, hashStableJson as hashHarnessReportStableJson, HARNESS_REPORT_PATH, loadHarnessReportForSync, normalizeHarnessReport, readHarnessReport, resolveHarnessReportPath, validateHarnessReport, writeHarnessReportArtifacts, } from './harness-report.js';
 import { renderHarnessAnalystChoice, renderHarnessAnalystLaunch, renderHarnessAnalystPreflight, renderHarnessAnalyzeHumanResult, renderHarnessProgress, } from './tui.js';
@@ -1623,7 +1623,7 @@ function buildCommandScanPlan(context, rootDir) {
     const rel = normalizePath(relative(context.cwd, rootDir)) || '.';
     const scope = explicitPath && rel !== '.' ? 'narrow' : 'broad';
     const machineReadable = context.outputMode !== 'human';
-    const approvalRequired = scope === 'broad' && !context.yes && !machineReadable && process.stdin.isTTY === true;
+    const approvalRequired = context.positional === 'analyze' && scope === 'broad' && !context.yes;
     return {
         scope,
         root: rel,
@@ -1632,10 +1632,10 @@ function buildCommandScanPlan(context, rootDir) {
             granted: !approvalRequired,
             reason: approvalRequired
                 ? 'broad scan requires confirmation'
-                : machineReadable
-                    ? 'machine-readable output'
-                    : context.yes
-                        ? '--yes'
+                : context.yes
+                    ? '--yes'
+                    : machineReadable
+                        ? 'machine-readable output'
                         : scope === 'narrow'
                             ? 'narrow path'
                             : 'non-interactive terminal',
@@ -1646,6 +1646,18 @@ function buildCommandScanPlan(context, rootDir) {
 async function approveScanIfNeeded(scanPlan, options = {}) {
     if (!scanPlan.approval.required)
         return;
+    if (options.context && (options.context.outputMode !== 'human' || process.stdin.isTTY !== true)) {
+        throw new CliInputRequiredError(options.message ?? 'Scan this project to build a Moda harness manifest?', {
+            id: 'harness_scan_approval',
+            question: options.message ?? 'Scan this project to build a Moda harness manifest?',
+            kind: 'confirm',
+            choices: [
+                { value: 'yes', label: 'Approve broad scan', resume_flags: ['--yes'] },
+                { value: 'no', label: 'Decline broad scan', resume_flags: ['--path', scanPlan.root === '.' ? './src' : scanPlan.root] },
+            ],
+            resume_command: ['moda', 'harness', 'analyze', '--yes'],
+        }, 'Re-run with `--yes` to approve the broad local read plan, or pass --path=<dir> for a narrower scan.');
+    }
     if (options.context?.outputMode === 'human') {
         writeHumanBlock(options.context, renderHarnessAnalystPreflight({
             root: scanPlan.root,