swipium 1.4.0 → 2.0.0

package/dist/tools/agent.js

@@ -1,13 +1,19 @@
 // Agent-efficiency layer. Compact, deterministic helpers so an MCP client spends fewer turns:
-// a one-glance session status, a blocker explainer, and a resume-from-blocker entry that consumes
+// the server instructions, a one-glance status (orientation without a session; state + next best
+// action with one), a blocker explainer, and a resume-from-blocker entry that consumes
 // user-provided input safely.
+import { realpathSync, statSync } from 'node:fs';
+import { isAbsolute, resolve as resolvePath, sep } from 'node:path';
 import { z } from 'zod';
-import { qaOk, qaError } from '../lib/result.js';
+import { qaOk, qaError, unknownSessionError } from '../lib/result.js';
 import { FAILURES, failureOwner, isSelfFixable } from '../oracle/failures.js';
 import { progressLine } from '../session/progress.js';
 import { readinessForSession } from '../report/readiness.js';
 import { SWIPIUM_VERSION, TOOL_COUNT, PROMPT_COUNT } from '../version.js';
 import { TEST_GOALS } from '../orchestration/goal.js';
+import { CAPABILITY_GROUPS } from '../core/capabilityGroups.js';
+import { recallTestThisIntent, markLoginDeclined } from '../orchestration/testThis/sessionIntent.js';
+import { SECRET_VAR_NAME } from '../flows/schema.js';
 function budgetRemaining(s) {
     const elapsedMin = (Date.now() - s.createdAt) / 60000;
     return {
@@ -16,127 +22,333 @@ function budgetRemaining(s) {
         screenshots: Math.max(0, s.budget.maxScreenshots - s.counters.screenshots),
     };
 }
-/** Deterministic "what next" given the session's observed state (optionally goal-aware). */
-function nextBestAction(s, goal) {
+/** Has this session already produced a durable generated asset (suite/flow/POM/test cases)?
+ *  Both generation paths leave a workaround-trail entry on success: the qa_test_this pipeline
+ *  records "generated a POM suite (…)" and qa_generate records "generated <target> test asset(s)
+ *  from recorded actions (qa_generate)". */
+function hasGeneratedAssets(s) {
+    return s.workarounds.some((w) => /^generated .*(suite|flow|pom|test)/i.test(w));
+}
+/** The mode qa_status reports (JSON and text alike). A WDA-less iOS simulator (SimctlDriver, kind
+ * 'simulator') is visual-only regardless of the stored mode, which only flips on a failed UI dump. */
+export function effectiveMode(s) {
+    // After a restart there is no live driver, but the persisted driverKind still tells the transport.
+    return (s.driver?.kind ?? s.driverKind) === 'simulator' ? 'visual-only' : s.mode;
+}
+const SIMULATOR_UDID_RE = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+/** Which platform the session's bound device is on. The live driver kind is authoritative
+ *  (simctl/WDA ⇒ iOS); a rehydrated session has no driver, so fall back to the device id shape:
+ *  iOS simulators are UUIDs, adb serials never are. */
+export function sessionPlatform(s) {
+    const kind = s.driver?.kind ?? s.driverKind;
+    if (kind === 'simulator' || kind === 'wda')
+        return 'ios';
+    if (kind === 'direct')
+        return 'android';
+    if (!s.device)
+        return undefined;
+    return SIMULATOR_UDID_RE.test(s.device) ? 'ios' : 'android';
+}
+/** Has a smoke pass run in this session? Persisted signals only: the qa_test_this pipeline's
+ *  `smoke_completed` milestone, or the launch_smoke note every smoke run records (qa_smoke too). */
+function smokeRan(s) {
+    return s.milestones?.smoke_completed != null || s.notes.some((n) => n.workflow === 'launch_smoke');
+}
+/** Latest time anything was exercised/observed (notes, findings, recorded actions). */
+function lastActivityAt(s) {
+    let t = 0;
+    for (const n of s.notes)
+        t = Math.max(t, n.at ?? 0);
+    for (const f of s.findings)
+        t = Math.max(t, f.at ?? 0);
+    for (const a of s.recordedActions)
+        t = Math.max(t, a.at ?? 0);
+    return t;
+}
+/** Milestone keys stamped by the agent-layer tools so qa_status can tell a terminal job's
+ *  recommended action was carried out (each overwritten with the latest time). */
+export const BLOCKER_ANSWERED_MILESTONE = 'blocker_answered';
+export const BLOCKER_EXPLAINED_MILESTONE = 'blocker_explained';
+/** Latest time the user answered a needs_input question: a stored input or a
+ *  qa_continue_from_blocker call (choices-only answers store no input). */
+function lastAnsweredAt(s) {
+    let t = s.milestones?.[BLOCKER_ANSWERED_MILESTONE] ?? 0;
+    for (const i of s.inputs ?? [])
+        t = Math.max(t, i.at ?? 0);
+    return t;
+}
+/** The newest report artifact, if one exists. */
+function latestReport(s) {
+    return s.artifacts.filter((a) => a.kind === 'report' && /\/report\/report-/.test(a.uri)).sort((a, b) => b.createdAt - a.createdAt)[0];
+}
+/** Deterministic "what next" given the session's observed state (optionally goal-aware).
+ *  An explicit state ladder, evaluated top-down, the first matching state wins. Every rung keys
+ *  on state its recommended tool CHANGES, so following the advice always advances the ladder:
+ *    1. a job is running                   > qa_job_status (poll it)
+ *    2. the last qa_test_this job ended    > its nextRecommendedAction (report / explain blocker /
+ *       and nothing happened since            answer the needs_input question), but only until that
+ *                                             action is observably done: a report newer than the job,
+ *                                             an answer (stored input / resume call) newer than the job
+ *                                             (> re-run the autopilot with it), or a qa_explain_blocker
+ *                                             {sessionId} call newer than the job. Replaying a done
+ *                                             action would loop, so the ladder moves on.
+ *    3. no device bound                    > qa_test_this  (orchestrate setup)
+ *    4. device but no app                  > qa_prepare_target (Android) / qa_prepare_ios_target (iOS sim)
+ *    5. no smoke yet and nothing recorded  > qa_smoke (records the smoke milestone)
+ *    6. findings, no report since          > qa_report
+ *    7. clean run, actions, no assets yet  > qa_generate (make the run durable)
+ *    8. no report since the last activity  > qa_report (wrap up)
+ *    9. a fresh report exists              > qa_get_artifact (read it, done; TERMINAL: the only
+ *                                             rung whose advice changes nothing, by design)
+ *  Exported for unit tests (test/nextBestAction.test.ts, test/orchStatusLadder.test.ts). */
+export function nextBestAction(s, goal) {
     const sid = s.id;
+    // 1. A job is still running: poll it before anything else.
     const lastJob = [...s.jobs.values()].sort((a, b) => b.startedAt - a.startedAt)[0];
     if (lastJob?.status === 'running')
-        return { tool: 'qa_job_status', why: `job ${lastJob.jobId} (${lastJob.kind}) is still running`, args: { sessionId: sid, jobId: lastJob.jobId } };
+        return {
+            tool: 'qa_job_status',
+            why: `job ${lastJob.jobId} (${lastJob.kind}) is still running`,
+            args: { sessionId: sid, jobId: lastJob.jobId },
+        };
+    // 2. The last autopilot job is terminal and nothing was exercised after it: its own
+    //    nextRecommendedAction is authoritative (a finished run must not be re-smoked).
+    const result = lastJob?.result;
+    const jobEnd = lastJob ? (lastJob.endedAt ?? lastJob.startedAt) : 0;
+    if (lastJob && result?.state && jobEnd >= lastActivityAt(s)) {
+        const nra = result.nextRecommendedAction;
+        const blocked = result.state === 'blocked' || result.state === 'unsafe';
+        const explained = (s.milestones?.[BLOCKER_EXPLAINED_MILESTONE] ?? 0) > jobEnd;
+        const answered = result.state === 'needs_input' && lastAnsweredAt(s) > jobEnd;
+        const reportedSince = (latestReport(s)?.createdAt ?? 0) > jobEnd;
+        if (blocked && !explained)
+            return {
+                tool: 'qa_explain_blocker',
+                why: `last job ${lastJob.jobId} ended ${result.state} (${result.failureCode ?? 'UNKNOWN'}): explain the blocker and relay the fix`,
+                args: { failureCode: result.failureCode ?? 'UNKNOWN', sessionId: sid },
+            };
+        // The question was answered (qa_continue_from_blocker stored the input): resume the autopilot
+        // with it. Starting that job is the state change; replaying the resume call would loop.
+        if (answered)
+            return {
+                tool: 'qa_test_this',
+                why: `the needs_input question of job ${lastJob.jobId} was answered; re-run the autopilot with the answer`,
+                args: { mode: 'execute', ...recallTestThisIntent(s), sessionId: sid, stopOnNeedsInput: false },
+            };
+        // A qa_report recommendation is satisfied by any report newer than the job.
+        const satisfied = blocked || (nra?.tool === 'qa_report' && reportedSince);
+        if (nra?.tool && !satisfied)
+            return {
+                tool: nra.tool,
+                why: result.state === 'needs_input'
+                    ? `last job ${lastJob.jobId} is waiting on one question: ${nra.why ?? 'answer it and resume'}`
+                    : `last job ${lastJob.jobId} ${result.state}: ${nra.why ?? 'follow its recommendation'}; no further calls needed after that`,
+                args: { ...(nra.args ?? {}) },
+            };
+    }
+    // 3. No device bound: orchestrate setup end-to-end.
     if (!s.device)
-        return { tool: 'qa_test_this', why: goal ? `no device/app prepared yet — run the autopilot for goal "${goal}"` : 'no device/app prepared yet — orchestrate setup', args: { sessionId: sid, mode: 'execute', ...(goal ? { goal } : {}) } };
+        return {
+            tool: 'qa_test_this',
+            why: goal ? `no device/app prepared yet, run the autopilot for goal "${goal}"` : 'no device/app prepared yet, orchestrate setup',
+            args: { sessionId: sid, mode: 'execute', ...(goal ? { goal } : {}) },
+        };
+    // 4. Device bound but no app launched: route to the platform's prepare tool (H9: after
+    //    `qa_ios boot` the bound device is a simulator; the Android-only qa_prepare_target would fail).
     if (!s.appId)
-        return { tool: 'qa_prepare_target', why: 'device bound but no app launched', args: { sessionId: sid } };
-    if (s.recordedActions.length === 0)
-        return { tool: 'qa_smoke', why: 'app is up but nothing exercised yet — run a smoke pass', args: { sessionId: sid } };
-    if (s.findings.length > 0)
-        return { tool: 'qa_report', why: `${s.findings.length} finding(s) recorded — summarize with evidence`, args: { sessionId: sid } };
-    if (s.recordedActions.length > 0)
-        return { tool: 'qa_suite_generate', why: 'actions recorded — turn the run into a durable POM suite', args: { sessionId: sid } };
-    return { tool: 'qa_report', why: 'wrap up and report', args: { sessionId: sid } };
-}
-/** The compact, current-version instruction set for coding agents (Milestone A). Pure + deterministic
- *  so it is snapshot-testable; it references the live SWIPIUM_VERSION / tool / prompt counts. */
-export function agentBrief() {
+        return sessionPlatform(s) === 'ios'
+            ? {
+                tool: 'qa_prepare_ios_target',
+                why: 'iOS simulator bound but no app launched',
+                args: { sessionId: sid, device: s.device },
+            }
+            : { tool: 'qa_prepare_target', why: 'device bound but no app launched', args: { sessionId: sid } };
+    // 5. App is up but nothing has been exercised (a smoke pass is a milestone, not an action count).
+    if (!smokeRan(s) && s.recordedActions.length === 0)
+        return { tool: 'qa_smoke', why: 'app is up but nothing exercised yet, run a smoke pass', args: { sessionId: sid } };
+    const report = latestReport(s);
+    const reportFresh = !!report && report.createdAt >= lastActivityAt(s);
+    // 6. Findings recorded: reporting them beats generating more assets.
+    if (s.findings.length > 0 && !reportFresh)
+        return { tool: 'qa_report', why: `${s.findings.length} finding(s) recorded, summarize with evidence`, args: { sessionId: sid } };
+    // 7. Clean run with recorded actions but no durable asset yet: make the run reusable.
+    if (s.findings.length === 0 && s.recordedActions.length > 0 && !hasGeneratedAssets(s))
+        return {
+            tool: 'qa_generate',
+            why: 'actions recorded, turn the run into a durable POM suite',
+            args: { sessionId: sid, target: 'suite' },
+        };
+    // 8. Wrap up with a report covering everything done so far.
+    if (!reportFresh)
+        return {
+            tool: 'qa_report',
+            why: hasGeneratedAssets(s)
+                ? 'clean run and test assets already generated, wrap up and report'
+                : 'smoke done, wrap up and report what was covered',
+            args: { sessionId: sid },
+        };
+    // 9. Terminal: a report newer than any activity exists. Read it; nothing else to do.
+    return {
+        tool: 'qa_get_artifact',
+        why: 'the run is reported. Read the report; no further Swipium calls are needed',
+        args: { uri: report.uri },
+    };
+}
+/** Server `instructions` (MCP InitializeResult.instructions): the operating manual clients may put
+ *  in the model's system prompt. Kept short on purpose; per-tool detail lives in tool descriptions
+ *  and docs/tools.md; qa_status (no sessionId) returns the same rules plus capability groups. */
+export const SERVER_INSTRUCTIONS = [
+    'Swipium runs mobile QA on local Android Emulators and iOS Simulators (physical devices are out of scope).',
+    '',
+    'First call: qa_test_this {mode:"execute"} (add goal, e.g. "release_gate"). It finds or builds the app, prepares an emulator/simulator, tests, and reports in a background job. It usually returns requiresConsent first (boot/install/build, see Consent), then {sessionId, jobId, state:"running"}.',
+    'Polling: qa_job_status {sessionId, jobId, waitMs:60000} until status is no longer "running". Then result.state is completed | blocked | unsafe | needs_input (none if cancelled), with reportUri. On completed, read it (qa_get_artifact {uri: reportUri}) and stop unless the user asks for more.',
+    'Orientation: qa_status without sessionId returns these rules + tool groups; with sessionId, session state and nextBestAction (goal biases it).',
+    '',
+    'needs_input: relay exactly the one returned question (fields, secret flags) to the user, then make the returned `resume` call (qa_continue_from_blocker) with their answer and follow its nextAction. Never invent extra questions.',
+    'blocked / unsafe: relay failureCode, owner, what Swipium tried, and the fix (qa_explain_blocker {failureCode, sessionId}). A build failure is not a test failure.',
+    'Ask the user only on needs_input or a consent request; otherwise keep going.',
+    'Consent: clients with MCP elicitation prompt the user directly. Otherwise show a requiresConsent result to the user and re-call with consentId + approve:true only after they agree. CONSENT_DECLINED / CONSENT_CANCELLED / CONSENT_REFUSED mean nothing ran - do not retry without asking.',
+    '',
+    'Project root: projectRoot arg, else MCP roots, else SWIPIUM_PROJECT_ROOT, else CLAUDE_PROJECT_DIR, else the server cwd if it is not / or $HOME and contains a project marker (package.json, app.json, pubspec.yaml, Gradle/Xcode files, Podfile, android/, ios/). On PROJECT_ROOT_UNRESOLVED pass an absolute projectRoot.',
+    'iOS Simulator without WebDriverAgent is visual-only: qa_snapshot/qa_act return BACKEND_UNSUPPORTED; use qa_screenshot + qa_visual, or attach WebDriverAgent via qa_wda. qa_test_this then runs a visual-only smoke.',
+    'Unknown arguments fail with INVALID_ARGUMENT (nothing runs). STALE_CLIENT means the client runs an outdated server: restart the client.',
+    'Feature work: read the app map first (qa_app_map_read / qa_app_map_query / qa_app_map_feature_scope); qa_test_feature tests one feature.',
+    'Low-level escape hatches: qa_start_session, qa_prepare_target / qa_prepare_ios_target, qa_snapshot, qa_act, qa_visual, qa_flow_run.',
+].join('\n');
+/** qa_status without a sessionId: first-call orientation (the operating rules + capability groups
+ *  by name). Pure + deterministic so it is snapshot-testable. */
+export function orientation(goal) {
     return {
-        version: SWIPIUM_VERSION,
+        orientation: true,
+        swipiumVersion: SWIPIUM_VERSION,
         tools: TOOL_COUNT,
         prompts: PROMPT_COUNT,
-        purpose: 'Turn a coding agent into a mobile QA tester. For a zero-context "test this" request, call the macro tool first.',
         firstCall: {
             tool: 'qa_test_this',
-            args: { mode: 'execute' },
-            note: 'Pass projectRoot if the client did not expose a workspace root. mode:"execute" runs the whole path as a background job.',
+            args: { mode: 'execute', ...(goal ? { goal } : {}) },
+            note: 'Pass projectRoot="/abs/path" if the client exposes no workspace root. Usually returns requiresConsent first (boot/install/build); after approval it runs as a background job.',
         },
         polling: {
             tool: 'qa_job_status',
-            args: { sessionId: '<from firstCall>', jobId: '<from firstCall>' },
+            args: { sessionId: '<from firstCall>', jobId: '<from firstCall>', waitMs: 60000 },
+            until: 'status is no longer "running" (done | failed | cancelled; a cancelled job has no result)',
             terminalStates: ['completed', 'blocked', 'unsafe', 'needs_input'],
         },
-        report: {
-            tool: 'qa_get_artifact',
-            args: { uri: '<reportUri from the terminal result>' },
-            rule: 'Fetch reportUri instead of calling more tools, unless nextRecommendedAction says otherwise.',
-        },
+        report: { tool: 'qa_get_artifact', args: { uri: '<reportUri from the terminal result>' } },
         goals: TEST_GOALS,
-        needsInputRule: 'Relay exactly the one returned question (with its fields/secret flags). Do not invent extra questions. Resume with the response\'s `resume` call.',
-        blockerRule: 'Relay failureCode, owner, what Swipium tried (attempted/workaroundsAttempted), and how to fix it. A build failure is not a test failure.',
-        stopRule: 'Stop and ask the user only on a needs_input state (credentials, monorepo target, destructive approval, signing, external service). Otherwise continue without user input.',
-        continueRule: 'For completed/blocked/unsafe states, summarize from the structured envelope and the report — no extra Swipium calls are required.',
-        mapRule: 'Before feature-focused testing, consult the durable App Knowledge Map: qa_app_map_read, qa_app_map_query, or qa_app_map_feature_scope to reuse what Swipium already learned instead of rediscovering the app. qa_test_this and qa_explore update the map automatically.',
-        macroTools: ['qa_test_this', 'qa_smoke', 'qa_explore', 'qa_report', 'qa_app_map_read'],
-        escapeHatches: ['qa_doctor', 'qa_start_session', 'qa_detect_context', 'qa_plan', 'qa_prepare_target', 'qa_prepare_ios_target', 'qa_ios', 'qa_wda', 'qa_act', 'qa_snapshot'],
+        rules: {
+            needsInput: 'Relay exactly the one returned question; make its `resume` call (qa_continue_from_blocker) with the answer, then follow nextAction.',
+            blocker: 'Relay failureCode, owner, what was tried, and the fix (qa_explain_blocker {failureCode, sessionId}). A build failure is not a test failure.',
+            consent: 'Clients with MCP elicitation prompt the user directly. Otherwise show requiresConsent to the user; re-call with consentId + approve:true only after they agree. CONSENT_DECLINED / CANCELLED / REFUSED: nothing ran, do not retry without asking.',
+            stop: 'Ask the user only on needs_input or a consent request; otherwise continue. After a completed job, read the report and stop.',
+            iosVisualOnly: 'An iOS Simulator without WebDriverAgent is visual-only: use qa_screenshot + qa_visual, or attach WebDriverAgent via qa_wda.',
+            appMap: 'Before feature testing, read the app map (qa_app_map_read / qa_app_map_query / qa_app_map_feature_scope).',
+        },
+        capabilityGroups: CAPABILITY_GROUPS.map((g) => ({ group: g.group, purpose: g.purpose, tools: [...g.tools] })),
+        nextBestAction: {
+            tool: 'qa_test_this',
+            why: goal ? `no session yet, run the autopilot for goal "${goal}"` : 'no session yet, start the autopilot',
+            args: { mode: 'execute', ...(goal ? { goal } : {}) },
+        },
     };
 }
 export function registerAgentTools(server, sessions) {
-    // ---- qa_agent_brief ----
-    server.registerTool('qa_agent_brief', {
-        title: 'Agent brief (how to drive Swipium)',
-        description: 'Read-only, cheap, deterministic. Returns the current-version instruction set for coding agents: the first call for low-context QA (qa_test_this), the polling + report-fetch flow, the NeedsInput/blocker rules, when to stop vs. continue, and which tools are macros vs. low-level escape hatches. Call this once at the start instead of inspecting the source tree.',
-        inputSchema: {},
-    }, async () => {
-        const b = agentBrief();
-        const summary = `Swipium v${b.version} (${b.tools} tools, ${b.prompts} prompts) — agent brief\n` +
-            `1. ${b.firstCall.tool} ${JSON.stringify(b.firstCall.args)}\n` +
-            `2. ${b.polling.tool} until state ∈ {${b.polling.terminalStates.join(', ')}}\n` +
-            `3. ${b.report.tool} { uri: reportUri }\n` +
-            'needs_input -> ask the one returned question; otherwise continue.';
-        return qaOk(b, summary);
-    });
     // ---- qa_status ----
     server.registerTool('qa_status', {
-        title: 'Session status (compact)',
-        description: 'A concise snapshot of a session for an agent: project root/framework, bound device + app, budget remaining, counters, recorded actions, findings/notes, last job, and the safe fallbacks taken (workarounds). Read-only, cheap — call between steps instead of re-deriving state.',
-        inputSchema: { sessionId: z.string() },
-    }, async ({ sessionId }) => {
+        title: 'Status, orientation, and next step',
+        description: 'Without sessionId: first-call orientation: how to drive Swipium (first call, polling, stop rules) plus the tool groups. ' +
+            'With sessionId: compact session state (device, app, budget left, counters, findings, last job, workarounds, readiness) and ' +
+            'nextBestAction: the single next tool to call, with args and why. Pass goal to bias the recommendation. Cheap; call between steps.',
+        inputSchema: {
+            sessionId: z.string().optional().describe('Omit for orientation; pass to get that session state.'),
+            goal: z
+                .enum(TEST_GOALS)
+                .optional()
+                .describe('Bias nextBestAction toward this autopilot goal.'),
+        },
+    }, async ({ sessionId, goal }) => {
+        if (!sessionId) {
+            const o = orientation(goal);
+            const summary = `Swipium v${o.swipiumVersion} (${o.tools} tools, ${o.prompts} prompts)\n` +
+                `1. ${o.firstCall.tool} ${JSON.stringify(o.firstCall.args)}\n` +
+                `2. ${o.polling.tool} {sessionId, jobId, waitMs} until status ≠ running; result.state ∈ {${o.polling.terminalStates.join(', ')}}\n` +
+                `3. ${o.report.tool} { uri: reportUri }, then stop\n` +
+                'requiresConsent > show it to the user; needs_input > ask the one returned question; otherwise continue.\n' +
+                o.capabilityGroups.map((g) => `[${g.group}] ${g.tools.join(', ')}`).join('\n');
+            return qaOk(o, summary);
+        }
         const s = sessions.get(sessionId);
         if (!s)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+            return unknownSessionError(sessionId, [
+                'Call qa_status without sessionId for orientation, or qa_start_session / qa_test_this to create a session.',
+            ]);
         const remaining = budgetRemaining(s);
         const lastJob = [...s.jobs.values()].sort((a, b) => b.startedAt - a.startedAt)[0];
-        const next = nextBestAction(s);
+        const next = nextBestAction(s, goal);
         const status = {
-            sessionId: s.id, root: s.root, device: s.device ?? null, appId: s.appId ?? null, mode: s.mode,
-            budgetRemaining: remaining, counters: s.counters,
-            recordedActions: s.recordedActions.length, findings: s.findings.length, notes: s.notes.length,
-            workarounds: s.workarounds, inputsProvided: s.inputs.map((i) => i.varName),
+            sessionId: s.id,
+            root: s.root,
+            device: s.device ?? null,
+            appId: s.appId ?? null,
+            mode: effectiveMode(s),
+            budgetRemaining: remaining,
+            counters: s.counters,
+            recordedActions: s.recordedActions.length,
+            findings: s.findings.length,
+            notes: s.notes.length,
+            workarounds: s.workarounds,
+            inputsProvided: s.inputs.map((i) => i.varName),
             readiness: readinessForSession(s),
-            lastJob: lastJob ? { jobId: lastJob.jobId, kind: lastJob.kind, status: lastJob.status, progress: lastJob.progress, progressDetail: lastJob.progressDetail ?? null } : null,
+            lastJob: lastJob
+                ? {
+                    jobId: lastJob.jobId,
+                    kind: lastJob.kind,
+                    status: lastJob.status,
+                    progress: lastJob.progress,
+                    progressDetail: lastJob.progressDetail ?? null,
+                }
+                : null,
             nextBestAction: next,
         };
         const progLine = progressLine(lastJob?.progressDetail);
-        const summary = `session ${s.id} — ${s.device ?? 'no device'}${s.appId ? ` / ${s.appId}` : ''} (mode=${s.mode})\n` +
+        const summary = `session ${s.id}: ${s.device ?? 'no device'}${s.appId ? ` / ${s.appId}` : ''} (mode=${status.mode})\n` +
             `budget left: ${remaining.minutes}m / ${remaining.actions} actions / ${remaining.screenshots} shots\n` +
             `recorded=${s.recordedActions.length} findings=${s.findings.length} notes=${s.notes.length}` +
-            (lastJob ? `\nlast job: ${lastJob.kind} [${lastJob.status}]${progLine ? `\n  ${progLine}` : lastJob.progress ? ` ${lastJob.progress}` : ''}` : '') +
+            (lastJob
+                ? `\nlast job: ${lastJob.kind} [${lastJob.status}]${progLine ? `\n  ${progLine}` : lastJob.progress ? ` ${lastJob.progress}` : ''}`
+                : '') +
             (s.workarounds.length ? `\nworkarounds: ${s.workarounds.length}` : '') +
-            `\n→ next: ${next.tool} — ${next.why}`;
+            `\nnext: ${next.tool} ${JSON.stringify(next.args)} (${next.why})`;
         return qaOk(status, summary);
     });
-    // ---- qa_next_best_action ----
-    server.registerTool('qa_next_best_action', {
-        title: 'What should I call next?',
-        description: 'Given the current session state, returns the single best next tool to call (with args) and why — so an agent does not have to reason out the orchestration sequence. Deterministic, read-only. Pass `goal` to bias the first call toward a specific autopilot intent.',
-        inputSchema: { sessionId: z.string(), goal: z.enum(['smoke', 'explore', 'create_automation_suite', 'release_gate', 'test_login', 'reproduce_bug']).optional() },
-    }, async ({ sessionId, goal }) => {
-        const s = sessions.get(sessionId);
-        if (!s)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
-        const next = nextBestAction(s, goal);
-        return qaOk({ nextBestAction: next }, `→ ${next.tool} ${JSON.stringify(next.args)} — ${next.why}`);
-    });
     // ---- qa_explain_blocker ----
     server.registerTool('qa_explain_blocker', {
         title: 'Explain a blocker',
-        description: 'Turn a typed failure code (e.g. AAB_NEEDS_BUNDLETOOL, WDA_SIGNING_FAILED, NO_BUILD_ARTIFACT) into a user-friendly explanation: what it means, who owns the fix (app / environment / Swipium / user), whether it is retry-safe, whether Swipium can fix it itself, and the exact recovery step. Use to relay a blocker to the user in plain language.',
+        description: 'Explain a failureCode in plain language: what it means, who owns the fix (app / environment / Swipium / user), whether ' +
+            'it is retry-safe or Swipium can fix it, and the recovery step.',
         inputSchema: {
-            failureCode: z.string().describe('A Swipium failure code (from a tool that returned isError with failureCode).'),
+            failureCode: z.string().describe('failureCode from a Swipium error.'),
             context: z.string().optional(),
+            sessionId: z.string().optional().describe('The blocked session (qa_status then moves past the blocker).'),
         },
-    }, async ({ failureCode, context }) => {
+    }, async ({ failureCode, context, sessionId }) => {
+        const sess = sessionId ? sessions.get(sessionId) : undefined;
+        if (sessionId && !sess)
+            return unknownSessionError(sessionId);
         const code = failureCode;
         const info = FAILURES[code];
         if (!info) {
-            return qaError({ what: `Unknown failure code "${failureCode}"`, changedState: false, retrySafe: true, nextSteps: ['Pass a code surfaced by a Swipium tool (the `failureCode` field of an error).'] });
+            return qaError({
+                what: `Unknown failure code "${failureCode}"`,
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Pass a code surfaced by a Swipium tool (the `failureCode` field of an error).'],
+            });
+        }
+        // Mark the blocker explained so qa_status's ladder stops recommending this call.
+        if (sess) {
+            sess.milestones[BLOCKER_EXPLAINED_MILESTONE] = Date.now();
+            sessions.persist(sess);
         }
         const owner = failureOwner(code);
         const ownerText = {
@@ -146,12 +358,18 @@ export function registerAgentTools(server, sessions) {
             user: 'you (provide input/approval/test data)',
         };
         const explanation = {
-            failureCode: code, bucket: info.bucket, owner, severity: info.severity,
-            retrySafe: info.retrySafe, canSwipiumFix: isSelfFixable(code),
-            whatItMeans: info.summary, whoFixesIt: ownerText[owner], howToFix: info.recovery,
+            failureCode: code,
+            bucket: info.bucket,
+            owner,
+            severity: info.severity,
+            retrySafe: info.retrySafe,
+            canSwipiumFix: isSelfFixable(code),
+            whatItMeans: info.summary,
+            whoFixesIt: ownerText[owner],
+            howToFix: info.recovery,
             context: context ?? null,
         };
-        const summary = `${code} — ${info.summary}\n` +
+        const summary = `${code}: ${info.summary}\n` +
             `owner: ${ownerText[owner]}; retry-safe: ${info.retrySafe}; Swipium can fix: ${isSelfFixable(code)}\n` +
             `fix: ${info.recovery}`;
         return qaOk(explanation, summary);
@@ -159,66 +377,257 @@ export function registerAgentTools(server, sessions) {
     // ---- qa_continue_from_blocker ----
     server.registerTool('qa_continue_from_blocker', {
         title: 'Resume after providing input',
-        description: 'Consume user-provided input for a NeedsInput question and return the next action. Secret values (passwords/OTP/tokens) are added to the session redaction set immediately (never stored in plaintext, never logged). Non-secret choices (platform, allowOutsideRoot, target) are echoed back as the args to re-invoke qa_test_this / qa_prepare_target with.',
+        description: 'Answer a needs_input question and get the next call. Secret values (passwords/OTP/tokens) join the redaction set at ' +
+            'once and are never echoed or logged (flows reference them as ${VAR}); non-secret choices (platform, device, target, allowOutsideRoot) map onto ' +
+            'the re-invocation args. Returns accepted, ignored[] (with how to apply), projectRoot for monorepo_target, and ' +
+            'nextAction.',
         inputSchema: {
             sessionId: z.string(),
-            kind: z.string().describe('The NeedsInput kind being answered (e.g. credentials, preferred_platform, artifact_outside_root).'),
-            values: z.record(z.union([z.string(), z.boolean()])).optional().describe('Field name → value. Secret fields are redacted on receipt.'),
-            secretFields: z.array(z.string()).optional().describe('Which value keys are secret (default: password/otp/token-like names).'),
+            kind: z.string().describe('The needs_input kind (e.g. credentials, monorepo_target).'),
+            values: z
+                .record(z.union([z.string(), z.boolean()]))
+                .optional()
+                .describe('Field name > value. Secret fields are redacted on receipt.'),
+            secretFields: z.array(z.string()).optional().describe('Secret keys (default: password/otp/token-like names).'),
         },
     }, async ({ sessionId, kind, values, secretFields }) => {
         const s = sessions.get(sessionId);
         if (!s)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
-        const vals = values ?? {};
-        const secretRe = /pass|secret|token|otp|pin|cvv|key/i;
-        const isSecret = (k) => (secretFields?.includes(k)) || secretRe.test(k);
+            return unknownSessionError(sessionId);
+        const vals = { ...(values ?? {}) };
+        // Shared secret-name rule (flows/schema.ts); `code` covers OTP fields named code / verificationCode.
+        const secretRe = SECRET_VAR_NAME;
+        // "test pre-login only" (the credentials question's own fallback) is a DECISION, not an input:
+        // mark login out of scope for the session instead of reporting it as an unknown field.
+        const declined = (kind === 'credentials' || kind === 'otp_or_manual_verification') && extractDecline(vals);
+        if (declined)
+            markLoginDeclined(sessions, s);
+        const isSecret = (k) => secretFields?.includes(k) || secretRe.test(k);
         // Register inputs into the SECURE STORE (P0.5): each maps to a flow variable; secret values
         // join the redaction set and are NEVER echoed back. Generated flows reference the var name.
         const accepted = [];
         const storedVars = [];
-        const reInvokeArgs = { sessionId: s.id };
+        const choices = {};
         for (const [k, v] of Object.entries(vals)) {
             const secret = isSecret(k);
             if (typeof v === 'string' && (secret || /email|user|account|otp|code|token|pin/i.test(k))) {
                 const varName = inputVarName(k);
                 sessions.setInput(s, varName, v, secret, `needs_input:${kind}`);
                 storedVars.push(varName);
-                accepted.push(`${k} → \${${varName}}${secret ? ' (redacted)' : ''}`);
+                accepted.push(`${k} > \${${varName}}${secret ? ' (redacted)' : ''}`);
             }
             else {
-                accepted.push(`${k}=${v}`);
-                if (k === 'platform')
-                    reInvokeArgs.platform = v;
-                if (k === 'allowOutsideRoot')
-                    reInvokeArgs.allowOutsideRoot = v;
-                if (k === 'target' || k === 'device')
-                    reInvokeArgs.device = v;
-                if (k === 'developmentTeam' || k === 'provisioningProfile' || k === 'serviceEndpoint')
-                    reInvokeArgs[k] = v;
+                choices[k] = v;
             }
         }
+        // H1: map non-secret choices onto args the re-invoked tool ACTUALLY accepts; anything it
+        // doesn't consume is reported back as `ignored` (with how to apply it), never silently dropped.
+        const mapped = mapBlockerChoices(kind, choices, s.root);
+        if (mapped.error) {
+            sessions.persist(s);
+            return qaError({
+                failureCode: 'INVALID_ARGUMENT',
+                what: mapped.error,
+                changedState: storedVars.length > 0,
+                retrySafe: true,
+                nextSteps: [
+                    'Re-call qa_continue_from_blocker with target set to one of the offered candidate paths (absolute, or relative to the project root).',
+                ],
+            });
+        }
+        for (const [k, v] of Object.entries(choices))
+            if (!mapped.ignored.some((i) => i.field === k))
+                accepted.push(`${k}=${v}`);
+        if (mapped.projectRoot) {
+            // qa_test_this resolves an existing session's root from the SESSION (projectRoot is only
+            // read when creating one), so adopt the chosen app directory as the effective root; the
+            // same thing the single-candidate discovery path does.
+            s.root = mapped.projectRoot;
+            s.chosenTarget = mapped.projectRoot; // qa_test_this skips the monorepo question for this root
+        }
+        // Persisted answer marker: qa_status stops replaying the resume call once answered.
+        s.milestones[BLOCKER_ANSWERED_MILESTONE] = Date.now();
         sessions.persist(s);
         sessions.addWorkaround(s, `resumed from "${kind}" blocker with: ${accepted.join(', ') || '(no values)'}`);
+        const reInvokeArgs = { sessionId: s.id, ...mapped.args };
+        // Replay the ORIGINAL qa_test_this intent (goal/goalText/flags). A resume that drops it
+        // silently downgrades e.g. release_gate to the default smoke.
+        const intent = recallTestThisIntent(s);
         // Decide the resume action by kind.
         const reInvokeKinds = new Set([
-            'artifact_outside_root', 'preferred_platform', 'monorepo_target',
+            'artifact_outside_root',
+            'preferred_platform',
+            'monorepo_target',
             'signing_team',
-            'destructive_exploration_approval', 'external_service_required',
+            'destructive_exploration_approval',
+            'external_service_required',
         ]);
         // Every resume is a DIRECTLY executable call. Credentials/OTP are now registered as secure
         // inputs, so re-invoking the autopilot drives the authenticated flows with them (the macro
-        // tool resolves the already-prepared session/device and continues) — no bare qa_act guess.
-        const resume = kind === 'credentials' || kind === 'otp_or_manual_verification'
-            ? { tool: 'qa_test_this', why: 'credentials registered (redacted) — re-run the autopilot to drive authenticated flows with them', args: { sessionId: s.id, mode: 'execute', stopOnNeedsInput: false } }
-            : reInvokeKinds.has(kind)
-                ? { tool: 'qa_test_this', why: 're-run orchestration with your choice applied', args: { mode: 'execute', ...reInvokeArgs } }
-                : { tool: 'qa_test_this', why: 'resume orchestration', args: { mode: 'execute', ...reInvokeArgs } };
-        return qaOk({ kind, accepted, storedVariables: storedVars, nextAction: resume, secretsRegistered: accepted.filter((a) => a.includes('redacted')).length }, `Accepted ${accepted.length} field(s)${accepted.some((a) => a.includes('redacted')) ? ' (secrets redacted)' : ''}.` +
+        // tool resolves the already-prepared session/device and continues), not a bare qa_act guess.
+        const resume = declined
+            ? {
+                tool: 'qa_test_this',
+                why: kind === 'credentials'
+                    ? 'login marked out of scope for this session. Continue with pre-login coverage only (authenticated flows are reported as blocked, not failed)'
+                    : 'verification marked out of scope; flows behind it are skipped and reported as blocked',
+                args: { mode: 'execute', ...intent, sessionId: s.id, stopOnNeedsInput: false },
+            }
+            : kind === 'credentials' || kind === 'otp_or_manual_verification'
+                ? {
+                    tool: 'qa_test_this',
+                    why: storedVars.length
+                        ? 'credentials registered (redacted). Re-run the autopilot to drive authenticated flows with them'
+                        : 'no credentials were provided. Re-run the autopilot (pre-login coverage)',
+                    args: { mode: 'execute', ...intent, sessionId: s.id, stopOnNeedsInput: false },
+                }
+                : kind === 'destructive_exploration_approval' && mapped.approveDestructive
+                    ? {
+                        // qa_test_this has no destructive switch; the supported path is qa_explore's
+                        // candidate-bound approval: discover candidates first, then approve one exactly.
+                        tool: 'qa_explore',
+                        why: 'destructive exploration approved. Discover exact destructive candidates first (dry run), then approve one with safeMode:"approved_destructive_candidate"',
+                        args: { sessionId: s.id, safeMode: 'dry_run_destructive' },
+                    }
+                    : reInvokeKinds.has(kind)
+                        ? {
+                            tool: 'qa_test_this',
+                            why: 're-run orchestration with your choice applied',
+                            args: { mode: 'execute', ...intent, ...reInvokeArgs },
+                        }
+                        : { tool: 'qa_test_this', why: 'resume orchestration', args: { mode: 'execute', ...intent, ...reInvokeArgs } };
+        return qaOk({
+            kind,
+            accepted,
+            ...(declined ? { loginOutOfScope: true } : {}),
+            storedVariables: storedVars,
+            ignored: mapped.ignored,
+            ...(mapped.projectRoot ? { projectRoot: mapped.projectRoot } : {}),
+            nextAction: resume,
+            secretsRegistered: accepted.filter((a) => a.includes('redacted')).length,
+        }, (declined ? 'Login marked out of scope for this session. Testing continues pre-login only.\n' : '') +
+            `Accepted ${accepted.length} field(s)${accepted.some((a) => a.includes('redacted')) ? ' (secrets redacted)' : ''}.` +
             (storedVars.length ? `\nstored for replay: ${storedVars.join(', ')}` : '') +
-            `\n→ next: ${resume.tool} ${JSON.stringify(resume.args)} — ${resume.why}`);
+            (mapped.ignored.length ? `\nnot applied: ${mapped.ignored.map((i) => `${i.field} (${i.howToApply})`).join('; ')}` : '') +
+            `\nnext: ${resume.tool} ${JSON.stringify(resume.args)} (${resume.why})`);
     });
 }
+/** The qa_test_this input keys a blocker resume may set (mirrors its zod schema in
+ *  src/tools/testThis.ts; test/blockerResume.test.ts asserts they stay in lockstep). */
+export const TEST_THIS_RESUME_KEYS = ['projectRoot', 'platform', 'device', 'allowOutsideRoot'];
+function realOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolvePath(p);
+    }
+}
+function truthy(v) {
+    return v === true || (typeof v === 'string' && /^(true|yes|1)$/i.test(v.trim()));
+}
+/** Map a NeedsInput answer's non-secret choices onto re-invocation args (H1). Pure except for the
+ *  existence check on a monorepo target. Exported for tests. */
+export function mapBlockerChoices(kind, choices, sessionRoot) {
+    const out = { args: {}, ignored: [] };
+    const ignore = (field, value, howToApply) => out.ignored.push({ field, value, howToApply });
+    for (const [k, v] of Object.entries(choices)) {
+        switch (k) {
+            case 'platform':
+                if (v === 'android' || v === 'ios')
+                    out.args.platform = v;
+                else
+                    ignore(k, v, 'platform must be "android" or "ios"');
+                break;
+            case 'allowOutsideRoot':
+                out.args.allowOutsideRoot = truthy(v);
+                break;
+            case 'device':
+                if (typeof v === 'string' && v.trim())
+                    out.args.device = v.trim();
+                else
+                    ignore(k, v, 'device must be a serial/UDID string');
+                break;
+            case 'target': {
+                if (kind === 'monorepo_target') {
+                    // The monorepo question offers app DIRECTORIES. This is the project root, not a device.
+                    if (typeof v !== 'string' || !v.trim()) {
+                        out.error = 'monorepo target must be an app directory path';
+                        break;
+                    }
+                    const raw = v.trim();
+                    if (raw === '~' || raw.startsWith('~/') || raw.startsWith('~' + sep)) {
+                        out.error = `monorepo target "${v}" must be one of the offered app directories inside the project root (no ~ paths)`;
+                        break;
+                    }
+                    const abs = isAbsolute(raw) ? resolvePath(raw) : resolvePath(sessionRoot, raw);
+                    let isDir = false;
+                    try {
+                        isDir = statSync(abs).isDirectory();
+                    }
+                    catch {
+                        isDir = false;
+                    }
+                    if (!isDir) {
+                        out.error = `monorepo target "${v}" is not an existing directory (resolved to ${abs})`;
+                        break;
+                    }
+                    // The offered candidates are always app directories discovered UNDER the project root
+                    // (findMobileApps), so containment in the (real) root is the constraint: an answer can
+                    // never re-point the session at `/`, the home dir, or an unrelated tree.
+                    const realRoot = realOrSelf(sessionRoot);
+                    const realTarget = realOrSelf(abs);
+                    if (realTarget !== realRoot && !realTarget.startsWith(realRoot.endsWith(sep) ? realRoot : realRoot + sep)) {
+                        out.error = `monorepo target "${v}" (${realTarget}) is outside the project root ${realRoot}; pick one of the offered app directories`;
+                        break;
+                    }
+                    out.projectRoot = abs;
+                    out.args.projectRoot = abs;
+                }
+                else if (typeof v === 'string' && v.trim()) {
+                    out.args.device = v.trim();
+                }
+                else {
+                    ignore(k, v, 'target must be a device serial/UDID string');
+                }
+                break;
+            }
+            case 'approveDestructive':
+                out.approveDestructive = truthy(v);
+                if (!out.approveDestructive)
+                    ignore(k, v, 'exploration stays non-destructive (the default)');
+                break;
+            case 'developmentTeam':
+                ignore(k, v, 'qa_test_this does not take a signing team. Set ios.wda.developmentTeam in .swipium/config.json (or DEVELOPMENT_TEAM in the server environment), then resume');
+                break;
+            case 'provisioningProfile':
+                ignore(k, v, 'Swipium builds for the simulator and does not consume a provisioning profile. Configure it in Xcode if your scheme needs one');
+                break;
+            case 'serviceEndpoint':
+                ignore(k, v, 'Swipium cannot route the app to a service endpoint. Configure it in the app build/env (e.g. a staging config), then resume');
+                break;
+            default:
+                ignore(k, v, `not an input qa_test_this accepts (accepted: ${TEST_THIS_RESUME_KEYS.join(', ')})`);
+        }
+    }
+    return out;
+}
+const DECLINE_KEYS = /^(choice|fallback|fallbackOption|option|answer|decision|selected|preLoginOnly|decline|declined|skip)$/i;
+const DECLINE_TEXT = /pre-?login only|stay pre-?login|decline|no credentials|skip (login|flows requiring verification)|^skip$/i;
+/** Detect (and remove from `vals`) a "decline the input" answer: a fallback-option string such as
+ *  "test pre-login only", or a boolean preLoginOnly/decline flag. Exported for tests. */
+export function extractDecline(vals) {
+    let declined = false;
+    for (const [k, v] of Object.entries(vals)) {
+        if (!DECLINE_KEYS.test(k))
+            continue;
+        if ((typeof v === 'boolean' && v && /preLoginOnly|decline|skip/i.test(k)) || (typeof v === 'string' && DECLINE_TEXT.test(v.trim()))) {
+            declined = true;
+            delete vals[k];
+        }
+    }
+    return declined;
+}
 /** Map a NeedsInput field name to its canonical Swipium flow variable (P0.5). */
 function inputVarName(field) {
     const f = field.toLowerCase();