@moda-ai/cli 1.17.1 → 1.18.0

package/dist/analyst-tui.js

@@ -176,7 +176,7 @@ export function renderAnalystTuiFrame(state, options = {}) {
         .map(([name, count]) => `${name} ${count}`)
         .join(', ') || 'none yet';
     const lines = [];
-    lines.push(`${bold('Moda Analyst')} ${dim('Step 4/7 Harness Discovery')}`);
+    lines.push(`${bold('Moda Analyst')} ${dim('Step 4/5 Set up')}`);
     lines.push(rule(width));
     lines.push(`${spinnerText} ${state.adapterName} ${dim('read-only repository access')}  ${dim(`elapsed ${formatDuration(elapsedSeconds)}`)}  ${dim(state.sawOutput ? `last output ${formatDuration(quietForSeconds)} ago` : 'waiting for first output')}`);
     lines.push('');

package/dist/cli.js

@@ -137,6 +137,7 @@ Commands:
   keys create                      Create a local key descriptor
   config show                      Show resolved Moda config
   harness analyze                  Produce a cited structured harness report
+  harness pull                     Fetch a server-side analyze run (status, or result when done)
   harness validate-report          Validate .moda/harness-report.json citations
   harness approve                  Approve a validated harness report for sync
   harness scan                     Discover local runtime agents and write .moda/harness.json
@@ -273,6 +274,7 @@ Examples:
   moda harness analyze --analyst=claude --no-tui
   moda harness analyze --analyst=claude --summary
   moda harness analyze --analyst=local-scan --summary
+  moda harness pull --sync
   moda harness validate-report
   moda harness approve --yes
   moda harness sync --from-report .moda/harness-report.json
@@ -872,6 +874,7 @@ export const commandRegistry = createCommandRegistry([
         examples: [
             'moda harness analyze --summary',
             'moda harness analyze --remote',
+            'moda harness pull --sync',
             'moda harness approve --yes',
             'moda harness sync --from-report .moda/harness-report.json',
             'moda harness explain --agent=agent_support',

package/dist/harness-remote.d.ts

@@ -6,15 +6,101 @@
  * (`POST /v1/harness/analyze`), polls `GET /v1/harness/analyze/:id` for the
  * validated report, then writes the same local artifacts and emits the same
  * lifecycle events as the local analyze paths.
+ *
+ * The flow is split into composable pieces so callers can overlap or detach it:
+ * `startRemoteAnalyze` (snapshot + upload + POST), `pollRemoteAnalyzeUntilDone`
+ * (status loop with an `onProgress` hook), and `finalizeRemoteAnalyzeResult`
+ * (repair + local validation + artifact writes). `runRemoteHarnessAnalyst`
+ * composes all three for `moda harness analyze --remote`, and `moda harness
+ * pull` (runHarnessPull) resumes a detached run from the
+ * `.moda/harness-remote-run.json` state file.
  */
 import type { CommandContext } from './command-context.js';
 import { type HarnessCommandScanPlan, type HarnessTenantContext } from './harness.js';
+/** Per-repo pointer to the most recent server-side analysis run. */
+export declare const HARNESS_REMOTE_RUN_STATE_PATH: string;
+/**
+ * Small state file written on start and on terminal states so `moda harness
+ * pull` and `moda harness status` can find a run after the starting process
+ * exited. Snake_case keys match the wire contract.
+ */
+export interface HarnessRemoteRunState {
+    run_id: string;
+    started_at_iso: string;
+    status: 'running' | 'completed' | 'failed';
+}
+/**
+ * Optional intermediate progress attached by newer hosted runners to
+ * `accepted`/`running` status responses. Older servers omit it.
+ */
+export interface RemoteAnalyzeProgress {
+    phase?: string;
+    message?: string;
+    tool_calls?: number;
+    updated_ms?: number;
+}
+export interface RemoteAnalyzeStatus {
+    success: boolean;
+    status: 'accepted' | 'running' | 'completed' | 'failed';
+    report?: unknown;
+    validation?: unknown;
+    error?: string;
+    progress?: RemoteAnalyzeProgress;
+}
 /**
  * True when `moda harness analyze` should run server-side (Moda-hosted) instead
  * of spawning a local coding agent: `--remote` (flags.remote === 'true') or the
  * `MODA_HARNESS_REMOTE` env opt-in.
  */
 export declare function isRemoteHarnessAnalyze(context: CommandContext): boolean;
+/** Read `.moda/harness-remote-run.json`; undefined when absent or unparseable. */
+export declare function readRemoteRunState(rootDir: string): HarnessRemoteRunState | undefined;
+/**
+ * Snapshot + upload + POST. Emits the inventory/upload lifecycle events,
+ * persists `.moda/harness-remote-run.json` with status `running`, and returns
+ * the accepted run id without waiting for the analysis.
+ */
+export declare function startRemoteAnalyze(options: {
+    context: CommandContext;
+    rootDir: string;
+}): Promise<{
+    runId: string;
+    snapshotTruncated: boolean;
+}>;
+/**
+ * Poll `GET /v1/harness/analyze/:id` until the run is terminal, the deadline
+ * passes, or `signal` aborts. `onProgress` fires after every poll with the
+ * latest status and any server-attached progress, so callers can render a live
+ * board; the poll cadence (3s doubling to 15s) is unchanged.
+ */
+export declare function pollRemoteAnalyzeUntilDone(options: {
+    context: CommandContext;
+    runId: string;
+    onProgress?: (update: {
+        status: RemoteAnalyzeStatus['status'];
+        progress?: RemoteAnalyzeProgress;
+    }) => void;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<RemoteAnalyzeStatus>;
+/**
+ * Turn a terminal (or timed-out) status payload into the local result: repair
+ * the report from local source, re-validate, write `.moda` artifacts, emit the
+ * artifact/validation events, and update the run state file. Shared by
+ * `moda harness analyze --remote` and `moda harness pull`. Throws for runs the
+ * client cannot recover; a timed-out non-terminal run keeps the state file at
+ * `running` so `moda harness pull` can resume it later.
+ */
+export declare function finalizeRemoteAnalyzeResult(options: {
+    context: CommandContext;
+    rootDir: string;
+    scanPlan: HarnessCommandScanPlan;
+    runId: string;
+    final: RemoteAnalyzeStatus;
+    snapshotTruncated?: boolean;
+}): {
+    exitCode: number;
+};
 /**
  * Server-side ("Moda-hosted") harness analysis. Builds a safe source snapshot,
  * uploads it to the ingest worker, polls for the validated report, then writes
@@ -30,4 +116,20 @@ export declare function runRemoteHarnessAnalyst(options: {
 }): Promise<{
     exitCode: number;
 }>;
+/**
+ * `moda harness pull [--run-id=<id>] [--sync]`: fetch the status of a
+ * server-side analysis run once (default run id from
+ * `.moda/harness-remote-run.json`). Still running: print status + progress and
+ * exit 0. Completed: finalize exactly like `harness analyze --remote` (repair,
+ * validate, write `.moda` artifacts); with `--sync` also approve + `harness
+ * sync --from-report` best-effort, the way `moda init` does. Failed: error,
+ * exit 1.
+ */
+export declare function runHarnessPull(options: {
+    context: CommandContext;
+    rootDir: string;
+    scanPlan: HarnessCommandScanPlan;
+}): Promise<{
+    exitCode: number;
+}>;
 //# sourceMappingURL=harness-remote.d.ts.map

package/dist/harness-remote.js

@@ -6,14 +6,26 @@
  * (`POST /v1/harness/analyze`), polls `GET /v1/harness/analyze/:id` for the
  * validated report, then writes the same local artifacts and emits the same
  * lifecycle events as the local analyze paths.
+ *
+ * The flow is split into composable pieces so callers can overlap or detach it:
+ * `startRemoteAnalyze` (snapshot + upload + POST), `pollRemoteAnalyzeUntilDone`
+ * (status loop with an `onProgress` hook), and `finalizeRemoteAnalyzeResult`
+ * (repair + local validation + artifact writes). `runRemoteHarnessAnalyst`
+ * composes all three for `moda harness analyze --remote`, and `moda harness
+ * pull` (runHarnessPull) resumes a detached run from the
+ * `.moda/harness-remote-run.json` state file.
  */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createCommandContext, stringOption } from './command-context.js';
 import { resolveApiKey, resolveIngestUrl } from './config.js';
 import { CliInputError } from './errors.js';
+import { stripAnsi } from './markdown-terminal.js';
 import { normalizeHarnessReport, stampRemoteSnapshotTruncation, validateHarnessReport, writeHarnessReportArtifacts, } from './harness-report.js';
-import { buildSourceSnapshot, emitWrittenArtifacts, numericEnv, numericEnvAllowZero, repairExternalAnalystReport, sleep, summarizeHarness, summarizeInvalidAnalystReport, truncateText, writeHarnessAnalyzeResult, writeHarnessArtifacts, writeHumanProgress, } from './harness.js';
+import { buildSourceSnapshot, emitWrittenArtifacts, numericEnv, numericEnvAllowZero, repairExternalAnalystReport, runHarnessCommand, sleep, summarizeHarness, summarizeInvalidAnalystReport, truncateText, writeHarnessAnalyzeResult, writeHarnessArtifacts, writeHumanProgress, } from './harness.js';
 /**
  * Client poll deadline. Must exceed the server's total analysis budget
- * (MODA_HARNESS_ANALYZE_TOTAL_BUDGET_MS, default 30m — full attempts plus the
+ * (MODA_HARNESS_ANALYZE_TOTAL_BUDGET_MS, default 30m: full attempts plus the
  * sharded fallback), or the client reports a bogus "did not finish" while the
  * hosted run is still working; polling also keeps the hosted container awake.
  */
@@ -22,8 +34,17 @@ const DEFAULT_REMOTE_POLL_INITIAL_MS = 3_000;
 const DEFAULT_REMOTE_POLL_MAX_MS = 15_000;
 /** Lower bound on the inter-poll delay so a 0 interval can't busy-loop the status endpoint. */
 const MIN_REMOTE_POLL_DELAY_MS = 250;
+/**
+ * Consecutive status-poll failures tolerated before the poll gives up. A
+ * hosted run stays healthy across a transient blip (a network hiccup, a proxy
+ * 5xx, or a GET racing the container's run-state write), and aborting a
+ * 30-minute analysis over one failed GET would waste the whole run.
+ */
+const REMOTE_POLL_MAX_CONSECUTIVE_FAILURES = 4;
 const REMOTE_UPLOAD_TIMEOUT_MS = 120_000;
 const REMOTE_STATUS_TIMEOUT_MS = 30_000;
+/** Per-repo pointer to the most recent server-side analysis run. */
+export const HARNESS_REMOTE_RUN_STATE_PATH = join('.moda', 'harness-remote-run.json');
 /**
  * True when `moda harness analyze` should run server-side (Moda-hosted) instead
  * of spawning a local coding agent: `--remote` (flags.remote === 'true') or the
@@ -34,8 +55,8 @@ export function isRemoteHarnessAnalyze(context) {
     // as the number 1 rather than the string '1'; accept every truthy spelling.
     const flag = context.flags.remote;
     // An explicit local opt-out (`--local` / `--no-remote` / `--remote=false|0`)
-    // wins over the `MODA_HARNESS_REMOTE` env, so callers that force local — the
-    // `moda init` local path and its remote-failure fallback — stay local even
+    // wins over the `MODA_HARNESS_REMOTE` env, so callers that force local (the
+    // `moda init` local path and its remote-failure fallback) stay local even
     // when the env is set. `no-remote` may arrive kebab- or snake-cased depending
     // on the caller (real CLI parsing snake-cases; internal callers do not).
     const noRemote = context.flags['no-remote'] ?? context.flags.no_remote;
@@ -49,23 +70,66 @@ export function isRemoteHarnessAnalyze(context) {
     const env = (context.env.MODA_HARNESS_REMOTE ?? '').trim().toLowerCase();
     return env !== '' && env !== '0' && env !== 'false';
 }
-/**
- * Server-side ("Moda-hosted") harness analysis. Builds a safe source snapshot,
- * uploads it to the ingest worker, polls for the validated report, then writes
- * the same local artifacts the local analyze path writes. Emits the same
- * lifecycle events so `--agent --stream` behaves consistently with the local
- * path.
- */
-export async function runRemoteHarnessAnalyst(options) {
-    const { context, rootDir } = options;
-    if (context.dryRun) {
-        throw new CliInputError('Remote harness analysis cannot run in dry-run mode.', 'Use `moda harness analyze --analyst=local-scan --dry-run` for deterministic local inspection.');
+/** Read `.moda/harness-remote-run.json`; undefined when absent or unparseable. */
+export function readRemoteRunState(rootDir) {
+    const path = join(rootDir, HARNESS_REMOTE_RUN_STATE_PATH);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed.run_id !== 'string' || parsed.run_id.length === 0)
+            return undefined;
+        return {
+            run_id: parsed.run_id,
+            started_at_iso: typeof parsed.started_at_iso === 'string' ? parsed.started_at_iso : '',
+            status: parsed.status === 'completed' || parsed.status === 'failed' ? parsed.status : 'running',
+        };
+    }
+    catch {
+        return undefined;
     }
+}
+/** Best-effort write: run tracking must never break the analyze pipeline itself. */
+function writeRemoteRunState(rootDir, state) {
+    try {
+        mkdirSync(join(rootDir, '.moda'), { recursive: true });
+        writeFileSync(join(rootDir, HARNESS_REMOTE_RUN_STATE_PATH), `${JSON.stringify(state, null, 2)}\n`);
+    }
+    catch {
+        // Ignore: a read-only tree loses run tracking, not the analysis result.
+    }
+}
+/** Mark the run terminal, preserving the original started_at when it is the same run. */
+function markRemoteRunTerminal(rootDir, runId, status) {
+    const existing = readRemoteRunState(rootDir);
+    writeRemoteRunState(rootDir, {
+        run_id: runId,
+        started_at_iso: existing && existing.run_id === runId && existing.started_at_iso
+            ? existing.started_at_iso
+            : new Date().toISOString(),
+        status,
+    });
+}
+/** Resolve the ingest endpoint + API key or fail with the standard remote-analyze guidance. */
+function resolveRemoteAnalyzeEndpoint(context) {
     const apiKey = resolveApiKey({ profile: context.profile, env: context.env });
     if (!apiKey) {
         throw new CliInputError('No Moda API key found for remote harness analysis.', 'Run `moda init` first (or set MODA_API_KEY), then rerun `moda harness analyze --remote`.');
     }
     const ingestUrl = resolveIngestUrl({ profile: context.profile, env: context.env }).replace(/\/+$/, '');
+    return { apiKey, ingestUrl };
+}
+/**
+ * Snapshot + upload + POST. Emits the inventory/upload lifecycle events,
+ * persists `.moda/harness-remote-run.json` with status `running`, and returns
+ * the accepted run id without waiting for the analysis.
+ */
+export async function startRemoteAnalyze(options) {
+    const { context, rootDir } = options;
+    if (context.dryRun) {
+        throw new CliInputError('Remote harness analysis cannot run in dry-run mode.', 'Use `moda harness analyze --analyst=local-scan --dry-run` for deterministic local inspection.');
+    }
+    const { apiKey, ingestUrl } = resolveRemoteAnalyzeEndpoint(context);
     context.output.writeEvent({
         event: 'progress',
         phase: 'inventory',
@@ -88,13 +152,18 @@ export async function runRemoteHarnessAnalyst(options) {
             message: 'Source snapshot is truncated; server-side analysis may be incomplete.',
             elapsed_ms: Date.now() - context.startedAt,
         });
-        writeHumanProgress(context, 'Warning: source snapshot is truncated — analysis may be incomplete.');
+        writeHumanProgress(context, 'Warning: source snapshot is truncated; analysis may be incomplete.');
     }
     const accepted = await postRemoteAnalyze(ingestUrl, apiKey, {
         snapshot,
         options: buildRemoteAnalyzeOptions(context.flags),
     });
     const runId = accepted.analysis_run_id;
+    writeRemoteRunState(rootDir, {
+        run_id: runId,
+        started_at_iso: new Date().toISOString(),
+        status: 'running',
+    });
     context.output.writeEvent({
         event: 'progress',
         phase: 'remote_wait',
@@ -102,26 +171,104 @@ export async function runRemoteHarnessAnalyst(options) {
         elapsed_ms: Date.now() - context.startedAt,
     });
     writeHumanProgress(context, `Moda Analyst (remote): analysis run ${runId} accepted; waiting for results...`);
-    const final = await pollRemoteAnalyze({ ingestUrl, apiKey, runId, context });
+    return { runId, snapshotTruncated: snapshot.truncated };
+}
+/**
+ * Poll `GET /v1/harness/analyze/:id` until the run is terminal, the deadline
+ * passes, or `signal` aborts. `onProgress` fires after every poll with the
+ * latest status and any server-attached progress, so callers can render a live
+ * board; the poll cadence (3s doubling to 15s) is unchanged.
+ */
+export async function pollRemoteAnalyzeUntilDone(options) {
+    const { context, runId, onProgress, signal } = options;
+    const { apiKey, ingestUrl } = resolveRemoteAnalyzeEndpoint(context);
+    const timeoutMs = options.timeoutMs ?? numericEnv('MODA_HARNESS_REMOTE_TIMEOUT_MS', DEFAULT_REMOTE_ANALYZE_TIMEOUT_MS);
+    const initialMs = numericEnvAllowZero('MODA_HARNESS_REMOTE_POLL_INITIAL_MS', DEFAULT_REMOTE_POLL_INITIAL_MS);
+    const maxMs = numericEnvAllowZero('MODA_HARNESS_REMOTE_POLL_MAX_MS', DEFAULT_REMOTE_POLL_MAX_MS);
+    const deadline = Date.now() + timeoutMs;
+    const url = `${ingestUrl}/v1/harness/analyze/${encodeURIComponent(runId)}`;
+    // Floor the inter-poll delay so a 0 (or unset) interval can't turn a long
+    // hosted run into a tight loop hammering the status endpoint.
+    const capMs = Math.max(maxMs, MIN_REMOTE_POLL_DELAY_MS);
+    let delay = Math.min(Math.max(initialMs, MIN_REMOTE_POLL_DELAY_MS), capMs);
+    let last = { success: false, status: 'accepted' };
+    let consecutiveFailures = 0;
+    while (true) {
+        try {
+            last = await remoteAnalyzeFetch(url, apiKey, { method: 'GET' }, REMOTE_STATUS_TIMEOUT_MS);
+            consecutiveFailures = 0;
+        }
+        catch (error) {
+            // Tolerate a bounded run of consecutive poll failures instead of
+            // aborting the (still healthy) hosted analysis on the first blip.
+            consecutiveFailures += 1;
+            if (consecutiveFailures >= REMOTE_POLL_MAX_CONSECUTIVE_FAILURES || signal?.aborted || Date.now() >= deadline) {
+                throw error;
+            }
+            context.output.writeEvent({
+                event: 'progress',
+                phase: 'remote_wait',
+                message: `Status poll failed (${consecutiveFailures}/${REMOTE_POLL_MAX_CONSECUTIVE_FAILURES}); retrying.`,
+                elapsed_ms: Date.now() - context.startedAt,
+            });
+            await sleep(Math.min(delay, Math.max(deadline - Date.now(), MIN_REMOTE_POLL_DELAY_MS)));
+            if (signal?.aborted)
+                return last;
+            delay = Math.min(delay * 2, capMs);
+            continue;
+        }
+        onProgress?.({ status: last?.status ?? 'running', progress: normalizeRemoteProgress(last?.progress) });
+        if (last?.status === 'completed' || last?.status === 'failed')
+            return last;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return last ?? { success: false, status: 'running' };
+        if (signal?.aborted)
+            return last ?? { success: false, status: 'running' };
+        context.output.writeEvent({
+            event: 'progress',
+            phase: 'remote_wait',
+            message: `Server-side analysis status: ${last?.status ?? 'running'}.`,
+            elapsed_ms: Date.now() - context.startedAt,
+        });
+        await sleep(Math.min(delay, remaining));
+        if (signal?.aborted)
+            return last;
+        delay = Math.min(delay * 2, capMs);
+    }
+}
+/**
+ * Turn a terminal (or timed-out) status payload into the local result: repair
+ * the report from local source, re-validate, write `.moda` artifacts, emit the
+ * artifact/validation events, and update the run state file. Shared by
+ * `moda harness analyze --remote` and `moda harness pull`. Throws for runs the
+ * client cannot recover; a timed-out non-terminal run keeps the state file at
+ * `running` so `moda harness pull` can resume it later.
+ */
+export function finalizeRemoteAnalyzeResult(options) {
+    const { context, rootDir, runId, final } = options;
     // A run that returned no report at all is a hard failure (timeout, or the
-    // hosted agent crashed before producing anything) — nothing to recover.
+    // hosted agent crashed before producing anything); nothing to recover.
     if (!final.report) {
+        if (final.status === 'failed')
+            markRemoteRunTerminal(rootDir, runId, 'failed');
         throw remoteAnalyzeHardFailure(final, runId);
     }
     // A `failed` run only qualifies for client-side recovery when the server tells
     // us the failure was its own REPORT VALIDATION (it produced a report but the
     // report-contract check failed). That is the one class the client can recover:
     // the uploaded snapshot is truncated/sampled, so the hosted analyst commonly
-    // leaves prompt/tool `body` (or citation lines) empty, and the client — which
-    // has the full local repo — can backfill those source-dependent gaps and
+    // leaves prompt/tool `body` (or citation lines) empty, and the client (which
+    // has the full local repo) can backfill those source-dependent gaps and
     // re-validate. Any other `failed` run (a crashed/aborted agent, which carries
     // an `error` string and no structured validation verdict) stays a hard failure
     // even if a partial report leaked through, so we never write or sync a report
     // from a hosted run the server aborted for a reason the client cannot repair.
     if (final.status === 'failed' && !serverFailedReportValidation(final)) {
+        markRemoteRunTerminal(rootDir, runId, 'failed');
         throw remoteAnalyzeHardFailure(final, runId);
     }
-    // The hosted analyst returned a report that failed SERVER-side validation —
+    // The hosted analyst returned a report that failed SERVER-side validation,
     // most often because it enumerated prompt/tool artifacts but left their `body`
     // empty, or because the uploaded snapshot was truncated so the server never
     // saw the source. The client has the full local repo, so `repairExternalAnalystReport`
@@ -133,7 +280,7 @@ export async function runRemoteHarnessAnalyst(options) {
         writeHumanProgress(context, 'Moda Analyst (remote): server validation incomplete; completing artifact bodies from local source...');
     }
     let report = repairExternalAnalystReport(normalizeHarnessReport(final.report), rootDir);
-    if (snapshot.truncated) {
+    if (options.snapshotTruncated) {
         report = stampRemoteSnapshotTruncation(report);
     }
     const validation = validateHarnessReport(report, rootDir);
@@ -158,6 +305,7 @@ export async function runRemoteHarnessAnalyst(options) {
         }));
     }
     emitWrittenArtifacts(context, written, 'Written by Moda Analyst (remote).');
+    markRemoteRunTerminal(rootDir, runId, validation.status === 'pass' ? 'completed' : 'failed');
     writeHarnessAnalyzeResult(context, {
         scanPlan: options.scanPlan,
         summary: validation.status === 'pass'
@@ -170,6 +318,117 @@ export async function runRemoteHarnessAnalyst(options) {
     });
     return { exitCode: validation.status === 'pass' ? 0 : 1 };
 }
+/**
+ * Server-side ("Moda-hosted") harness analysis. Builds a safe source snapshot,
+ * uploads it to the ingest worker, polls for the validated report, then writes
+ * the same local artifacts the local analyze path writes. Emits the same
+ * lifecycle events so `--agent --stream` behaves consistently with the local
+ * path.
+ */
+export async function runRemoteHarnessAnalyst(options) {
+    const { context, rootDir } = options;
+    const { runId, snapshotTruncated } = await startRemoteAnalyze({ context, rootDir });
+    const final = await pollRemoteAnalyzeUntilDone({ context, runId });
+    return finalizeRemoteAnalyzeResult({
+        context,
+        rootDir,
+        scanPlan: options.scanPlan,
+        runId,
+        final,
+        snapshotTruncated,
+    });
+}
+/**
+ * `moda harness pull [--run-id=<id>] [--sync]`: fetch the status of a
+ * server-side analysis run once (default run id from
+ * `.moda/harness-remote-run.json`). Still running: print status + progress and
+ * exit 0. Completed: finalize exactly like `harness analyze --remote` (repair,
+ * validate, write `.moda` artifacts); with `--sync` also approve + `harness
+ * sync --from-report` best-effort, the way `moda init` does. Failed: error,
+ * exit 1.
+ */
+export async function runHarnessPull(options) {
+    const { context, rootDir } = options;
+    const state = readRemoteRunState(rootDir);
+    const flagRunId = stringOption(context.flags['run-id'] ?? context.flags.run_id);
+    const runId = flagRunId ?? state?.run_id;
+    if (!runId) {
+        throw new CliInputError('No server-side harness analysis run to pull.', 'Start one with `moda harness analyze --remote` (or `moda init`), or pass --run-id=<id>.');
+    }
+    const { apiKey, ingestUrl } = resolveRemoteAnalyzeEndpoint(context);
+    const url = `${ingestUrl}/v1/harness/analyze/${encodeURIComponent(runId)}`;
+    const status = await remoteAnalyzeFetch(url, apiKey, { method: 'GET' }, REMOTE_STATUS_TIMEOUT_MS);
+    if (status?.status === 'accepted' || status?.status === 'running') {
+        const progress = normalizeRemoteProgress(status.progress);
+        writeHumanProgress(context, `Moda Analyst (remote): run ${runId} is still ${status.status}${progress?.message ? ` (${progress.message})` : ''}.`);
+        context.output.writeData({
+            runId,
+            status: status.status,
+            progress,
+            startedAt: state && state.run_id === runId && state.started_at_iso ? state.started_at_iso : undefined,
+            hint: 'Run `moda harness pull` again in a few minutes.',
+        });
+        return { exitCode: 0 };
+    }
+    const result = finalizeRemoteAnalyzeResult({
+        context,
+        rootDir,
+        scanPlan: options.scanPlan,
+        runId,
+        final: status,
+    });
+    if (result.exitCode === 0 && isTruthyFlagValue(context.flags.sync)) {
+        await approveAndSyncPulledReport(context);
+    }
+    return result;
+}
+/** Accept every truthy spelling a bare or internal `--sync` flag can arrive as. */
+function isTruthyFlagValue(value) {
+    return value === true || value === 1 || value === 'true' || value === '1' || value === 'yes';
+}
+/**
+ * Best-effort approve + `harness sync --from-report`, the same follow-up calls
+ * `moda init` makes after a successful analyze. A network blip must not fail
+ * the pull; the report artifacts are already on disk, and the user gets the
+ * manual recovery command instead.
+ */
+async function approveAndSyncPulledReport(context) {
+    const machine = context.outputMode !== 'human';
+    const agentMode = context.outputMode === 'agent' || context.outputMode === 'agent-stream';
+    const subFlags = {
+        yes: 'true',
+        quiet: 'true',
+        'no-telemetry': 'true',
+        ...(machine ? { json: 'true' } : {}),
+        ...(agentMode ? { agent: 'true' } : {}),
+        ...(context.profile ? { profile: context.profile } : {}),
+    };
+    try {
+        await runHarnessCommand(createCommandContext({
+            command: 'harness',
+            positional: 'approve',
+            positionals: ['approve'],
+            flags: subFlags,
+        }, { cwd: context.cwd, env: context.env }));
+        await runHarnessCommand(createCommandContext({
+            command: 'harness',
+            positional: 'sync',
+            positionals: ['sync'],
+            flags: { ...subFlags, 'from-report': 'true' },
+        }, { cwd: context.cwd, env: context.env }));
+        writeHumanProgress(context, 'Moda Analyst (remote): harness graph synced to Moda.');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        context.output.writeEvent({
+            event: 'warning',
+            phase: 'remote_sync',
+            message: `Harness sync skipped: ${message}`,
+            elapsed_ms: Date.now() - context.startedAt,
+        });
+        writeHumanProgress(context, `Harness sync skipped: ${message}. Run \`moda harness approve --yes && moda harness sync --from-report\` later to upload.`);
+    }
+}
 /** Build the terminal error for a remote run that cannot be recovered client-side. */
 function remoteAnalyzeHardFailure(final, runId) {
     const detail = final.status === 'failed'
@@ -183,7 +442,7 @@ function remoteAnalyzeHardFailure(final, runId) {
 }
 /**
  * True when a `failed` hosted run failed specifically because its own report
- * validation failed — the only server failure the client can recover. The hosted
+ * validation failed, the only server failure the client can recover. The hosted
  * service attaches a structured validation verdict (`{ status: 'fail', ... }`)
  * only when it produced a report that failed the report-contract check
  * (`apps/moda-harness-analyze` server.ts); an operational failure (crashed agent)
@@ -197,6 +456,38 @@ function serverFailedReportValidation(final) {
     return typeof validation === 'object' && validation !== null && !Array.isArray(validation)
         && validation.status === 'fail';
 }
+/**
+ * Strip ANSI/OSC escapes and bare control characters from a server-controlled
+ * progress string before it can reach a terminal. The hosted-analyze `phase`/
+ * `message` originate from LLM-agent tool inputs (file paths, commands) that a
+ * hostile repo or prompt injection can lace with escape sequences; the container
+ * relays them unsanitized. `moda init` scrubs them via the progress board's
+ * `oneLine`, but the standalone `moda harness pull` human path prints them
+ * directly — so sanitize once, here, where every consumer flows through. Mirrors
+ * `oneLine`'s ANSI + control-char stripping (without the display truncation).
+ */
+function sanitizeProgressText(text) {
+    return stripAnsi(text)
+        .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Keep only the documented progress fields; drop anything else a server sends. */
+function normalizeRemoteProgress(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const progress = {};
+    if (typeof raw.phase === 'string')
+        progress.phase = sanitizeProgressText(raw.phase);
+    if (typeof raw.message === 'string')
+        progress.message = sanitizeProgressText(raw.message);
+    if (typeof raw.tool_calls === 'number')
+        progress.tool_calls = raw.tool_calls;
+    if (typeof raw.updated_ms === 'number')
+        progress.updated_ms = raw.updated_ms;
+    return Object.keys(progress).length > 0 ? progress : undefined;
+}
 /** Map CLI flags to the optional server-side analyze options in the wire contract. */
 function buildRemoteAnalyzeOptions(flags) {
     const options = {};
@@ -220,35 +511,6 @@ async function postRemoteAnalyze(ingestUrl, apiKey, body) {
     }
     return parsed;
 }
-async function pollRemoteAnalyze(options) {
-    const { ingestUrl, apiKey, runId, context } = options;
-    const timeoutMs = numericEnv('MODA_HARNESS_REMOTE_TIMEOUT_MS', DEFAULT_REMOTE_ANALYZE_TIMEOUT_MS);
-    const initialMs = numericEnvAllowZero('MODA_HARNESS_REMOTE_POLL_INITIAL_MS', DEFAULT_REMOTE_POLL_INITIAL_MS);
-    const maxMs = numericEnvAllowZero('MODA_HARNESS_REMOTE_POLL_MAX_MS', DEFAULT_REMOTE_POLL_MAX_MS);
-    const deadline = Date.now() + timeoutMs;
-    const url = `${ingestUrl}/v1/harness/analyze/${encodeURIComponent(runId)}`;
-    // Floor the inter-poll delay so a 0 (or unset) interval can't turn a long
-    // hosted run into a tight loop hammering the status endpoint.
-    const capMs = Math.max(maxMs, MIN_REMOTE_POLL_DELAY_MS);
-    let delay = Math.min(Math.max(initialMs, MIN_REMOTE_POLL_DELAY_MS), capMs);
-    let last = { success: false, status: 'accepted' };
-    while (true) {
-        last = await remoteAnalyzeFetch(url, apiKey, { method: 'GET' }, REMOTE_STATUS_TIMEOUT_MS);
-        if (last?.status === 'completed' || last?.status === 'failed')
-            return last;
-        const remaining = deadline - Date.now();
-        if (remaining <= 0)
-            return last ?? { success: false, status: 'running' };
-        context.output.writeEvent({
-            event: 'progress',
-            phase: 'remote_wait',
-            message: `Server-side analysis status: ${last?.status ?? 'running'}.`,
-            elapsed_ms: Date.now() - context.startedAt,
-        });
-        await sleep(Math.min(delay, remaining));
-        delay = Math.min(delay * 2, capMs);
-    }
-}
 async function remoteAnalyzeFetch(url, apiKey, init, timeoutMs) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);