@clien-ai/mcp 0.8.1 → 0.10.0

package/dist/tools/interview-scripts.js

@@ -0,0 +1,370 @@
+/**
+ * `list_interview_scripts` (FUL-514) — the questions a run says are worth asking.
+ *
+ * Before this tool, MCP had the ACTION without the PLAN. An agent could call
+ * `interview_persona` but could not first read what the research decided was worth
+ * asking, so it either invented questions unanchored to the run's open hypotheses
+ * — in which case the answers cannot feed back into the claim spine — or
+ * re-derived them from `get_report`'s hypothesis list, which is the FUL-510
+ * failure again: an agent recomputing something the run already produced and
+ * stored. The web app has handed a human this screen for free since FUL-327.
+ *
+ * ⚠️ THIS TOOL NEVER GENERATES A SCRIPT. Scripts are the deterministic output of a
+ * research run (`agent/src/interview-script.ts`), written into the run's report
+ * and immutable thereafter. Deriving them on a miss would make a free read do
+ * model work and spend money on a GET, so a project with none gets the honest
+ * empty state and nothing else. The wording of that empty state matters as much as
+ * the guarantee: "no run has written scripts" is not "there is nothing worth
+ * asking".
+ *
+ * Contract:
+ *   - list_interview_scripts → GET /api/interview-scripts?projectId →
+ *       { interviewScripts: <script>[] | null, sourceRun: { id, createdAt } | null }
+ *
+ * ⚠️ VOCABULARY, and why this differs from `collections.ts`. The two collections
+ * and `get_market` read PROMOTED TABLES, so their endpoints return raw snake_case
+ * rows and those modules map at the tool boundary. Interview scripts are not a
+ * table — they live inside `validation_jobs.report_data.interviewScripts` — so
+ * `/api/interview-scripts` returns a shape the app has already mapped, ranked and
+ * joined to its hypotheses. The mapper below therefore NORMALISES (type-checks
+ * every field, degrades a bad one to null) rather than renames. It is still
+ * written out field by field, for the same reason the collection mappers are: the
+ * field list is part of the public MCP contract and must be readable in review.
+ *
+ * ⚠️ RANKING AND SELECTION ARE THE SERVER'S. Which run owns a project's scripts
+ * (`latestScriptedRunQuery` — newest non-scoped run that actually wrote an array)
+ * and what order they come in (`buildRankedScripts` — least-settled verdict first)
+ * are decided once, app-side, by the same functions the web screen renders from.
+ * Re-sorting here is what would let the two surfaces disagree about which
+ * hypothesis is most worth a real answer.
+ *
+ * Everything else follows its siblings: the shared `apiCall` client, the shared
+ * 401/404/400 mapping, and the rule that "I could not read the answer" and "the
+ * answer is none" must never look the same. Read-only, so a timeout is always safe
+ * to retry — no work lost, no credit spent.
+ */
+import { z } from 'zod';
+import { CollectionToolError, formatZodError, makeCtx, throwForResponse, } from './collections.js';
+import { apiCall } from './research.js';
+import { safeId, safeInline, truncate, collapseWhitespace } from './render-safety.js';
+const SCRIPTS_FETCH_TIMEOUT_MS = 30_000;
+export const ListInterviewScriptsInputSchema = z.object({
+    project_id: z
+        .string()
+        .uuid()
+        .describe('UUID of the project whose interview scripts to read. Get it from ' +
+        '`list_projects` (or `create_project`). Rejected with a 404 if you do not own the ' +
+        'project. Returns the STORED OUTPUT OF ONE SPECIFIC RESEARCH RUN — the scripts that ' +
+        'run wrote when it ran, one per hypothesis, ranked least-settled first — not a live ' +
+        'suggestion and not something generated when you call this. The run is named in the ' +
+        'result; pass its id to `get_report` for the hypotheses behind the questions. A ' +
+        'project can legitimately have NO scripts; that is reported as "no run has written ' +
+        'any", never as "there is nothing worth asking".'),
+});
+function asText(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+/**
+ * A 0–1 confidence, or null.
+ *
+ * Out-of-range and non-finite numbers become null rather than being printed. The
+ * app drops them for the same reason at its own render seam: a percentage derived
+ * from 999 reads as a measurement, and this tool has no way to caption it as
+ * nonsense in the one line it gets.
+ */
+function asFraction(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return null;
+    return value >= 0 && value <= 1 ? value : null;
+}
+export function toInterviewScriptEntry(row) {
+    return {
+        hypothesisId: asText(row.hypothesisId),
+        statement: asText(row.statement),
+        status: asText(row.status),
+        verdictLabel: asText(row.verdictLabel),
+        confidence: asFraction(row.confidence),
+        whoToAsk: asText(row.whoToAsk),
+        // A drifted null (or a string where an array belongs) costs the questions,
+        // never the script: the hypothesis it names is still worth reporting.
+        questions: Array.isArray(row.questions)
+            ? row.questions.filter((q) => typeof q === 'string')
+            : [],
+    };
+}
+export function toInterviewScriptsSourceRun(row) {
+    return { id: asText(row.id), createdAt: asText(row.createdAt) };
+}
+// ---------------------------------------------------------------------------
+// Render caps
+// ---------------------------------------------------------------------------
+/**
+ * Upper bound on scripts RENDERED, matching `report-digest.ts`'s `LIST_RENDER_CAP`
+ * for personas and hypotheses. A run writes one script per hypothesis and the
+ * producer's hypothesis cap is far below this, so it should never fire — but an
+ * unfired cap that would truncate silently is the thing this package refuses.
+ * When it fires it says so, and says where the rest are.
+ */
+const SCRIPT_RENDER_CAP = 25;
+/**
+ * Questions rendered per script. The generator writes exactly 3; the cap exists
+ * for a report written by some other build, and announces itself the same way.
+ */
+const QUESTION_RENDER_CAP = 12;
+const STATEMENT_MAX = 240;
+const WHO_TO_ASK_MAX = 240;
+const QUESTION_MAX = 300;
+const VERDICT_MAX = 40;
+const TIMESTAMP_MAX = 40;
+/**
+ * GET /api/interview-scripts for one project.
+ *
+ * ⚠️ THE NULL AND THE THROW ARE DIFFERENT ANSWERS, and the difference is decided by
+ * KEY PRESENCE, not truthiness. `{ "interviewScripts": null }` is the endpoint
+ * saying "no run has written scripts for this project" — a real, quotable fact. A
+ * 200 whose body has no `interviewScripts` key at all (an HTML error page from a
+ * proxy, a truncated response, a reshaped envelope) is the endpoint saying nothing,
+ * and must not arrive at an agent wearing the empty state's words: that empty state
+ * ends with "run `clien_research`", which DEBITS CREDITS. A transport failure read
+ * as "this project has no plan" can cost the user real money.
+ */
+async function fetchInterviewScripts(deps, projectId) {
+    const action = 'read the interview scripts';
+    const ctx = makeCtx(deps);
+    const query = new URLSearchParams({ projectId });
+    let response;
+    try {
+        response = await apiCall(ctx, 'GET', `/api/interview-scripts?${query.toString()}`, {
+            timeoutMs: SCRIPTS_FETCH_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+            throw new CollectionToolError(`Timed out after ${SCRIPTS_FETCH_TIMEOUT_MS / 1000}s trying to ${action}. ` +
+                'Try again in a moment — this is a read, so nothing was spent and nothing was lost.');
+        }
+        throw err;
+    }
+    if (!response.ok)
+        await throwForResponse(response, deps, action, projectId);
+    const json = (await response.json().catch(() => null));
+    const unreadable = new CollectionToolError(`Could not ${action} — the server returned a 200 with an unreadable body ` +
+        '(no `interviewScripts` key). This is NOT "the project has no interview scripts": the ' +
+        'request failed and scripts may well exist. Retry — this is a read, so nothing was spent ' +
+        'and nothing was lost. Do not tell anyone this project has no interview plan on the ' +
+        'strength of this, and do not start a paid research run because of it.');
+    if (json === null ||
+        typeof json !== 'object' ||
+        Array.isArray(json) ||
+        !('interviewScripts' in json)) {
+        throw unreadable;
+    }
+    const rawRun = json.sourceRun;
+    const sourceRun = rawRun !== null && typeof rawRun === 'object' && !Array.isArray(rawRun)
+        ? toInterviewScriptsSourceRun(rawRun)
+        : null;
+    const raw = json.interviewScripts;
+    if (raw === null)
+        return { scripts: null, sourceRun };
+    if (!Array.isArray(raw))
+        throw unreadable;
+    const scripts = raw
+        .filter((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry))
+        .map(toInterviewScriptEntry);
+    return { scripts, sourceRun };
+}
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+/**
+ * The provenance sentence, in the TEXT channel because that is the one an agent
+ * always receives (FUL-243: `_meta` is a mirror, Claude Code drops it).
+ *
+ * A run id this client cannot state EXACTLY gets its own sentence rather than
+ * silence. Silence would read as "there is nothing to say about where these came
+ * from", when the truth is that the provenance is unknown — and a question set
+ * with unknown provenance is exactly the one an agent must not attribute to
+ * "the research".
+ */
+function provenanceLine(runId, createdAt) {
+    const safe = safeId(runId);
+    const when = safeInline(createdAt, TIMESTAMP_MAX);
+    if (!safe) {
+        return ('PROVENANCE: these scripts name NO source run — either the response omitted it or the ' +
+            'run behind them has since been deleted. Report them as recorded, never as "run X ' +
+            'recommends asking".');
+    }
+    return (`PROVENANCE: every script above was written by research run ${safe}` +
+        (when ? ` (recorded ${when})` : '') +
+        '. A report is an immutable snapshot, so the verdicts beside each question are that run\'s, ' +
+        `not today's — call \`get_report\` with job_id=${safe} for the hypotheses behind them.`);
+}
+/**
+ * The linkage instruction.
+ *
+ * ⚠️ It names PARAMETERS now, not a thing to remember (FUL-577). This line used to
+ * ask the agent to carry `hypothesisId` forward by hand, because `interview_persona`
+ * took no hypothesis id and `interviews` had no column for one — the strongest thing
+ * a read-only tool could do, and still a written instruction rather than a stored
+ * relation. `interview_persona action:start` now accepts the pair and the row keeps
+ * it, so telling an agent to remember something it can instead write down would be
+ * the worst of both.
+ *
+ * BOTH halves, because an id alone is ambiguous: hypotheses live inside a run's
+ * `report_data`, so the same `H3` recurs across runs of one project meaning
+ * different things. That is why `sourceRun.id` is named here and not merely
+ * available in the provenance line.
+ */
+const LINKAGE_LINE = 'LINKAGE: each script names the `hypothesisId` it was written to test. Pass it to ' +
+    '`interview_persona action:start` as `hypothesis_id`, together with this call\'s ' +
+    '`sourceRun.id` as `hypothesis_run_id`, and the interview RECORDS which hypothesis it tested — ' +
+    'you no longer have to carry the id through the conversation, and `get_interview` / ' +
+    '`list_interviews` hand it back. Both parameters or neither: an id is only meaningful against ' +
+    'the run that defined it.';
+/**
+ * The trust caveat.
+ *
+ * A verdict printed beside a question reads as settled unless something says
+ * otherwise (FUL-247). These verdicts are the run's reading of its own hypothesis,
+ * not the grading of a claim: the per-claim GROUNDED / SPECULATION / NO_RECEIPT
+ * states live in the source run's claim spine, which this separately released
+ * client cannot reconstruct.
+ */
+const SCRIPTS_TRUST_LINE = 'TRUST: the verdict and confidence on each script are the source run\'s reading of that ' +
+    'hypothesis, not a graded claim. Nothing here carries a GROUNDED / SPECULATION / NO_RECEIPT ' +
+    'state — read the source run with `get_report` for those. A high confidence is a reason to ask ' +
+    'a different question, never a reason to skip asking.';
+const CHANNEL_NOTE = 'The full record is in `structuredContent.interviewScripts` (also mirrored in `_meta`).';
+/** `Weak signal (inconclusive), confidence 52%` — or the honest partial forms. */
+function verdictClause(script) {
+    const label = safeInline(script.verdictLabel, VERDICT_MAX);
+    const status = safeInline(script.status, VERDICT_MAX);
+    const confidence = script.confidence === null ? null : `confidence ${Math.round(script.confidence * 100)}%`;
+    const verdict = label && status ? `${label} (${status})` : label ?? status ?? 'verdict not recorded';
+    return confidence ? `${verdict}, ${confidence}` : `${verdict}, confidence not recorded`;
+}
+/** The question list for one script, capped and — when capped — saying so. */
+function questionBlock(questions) {
+    const flat = questions
+        .map((q) => collapseWhitespace(typeof q === 'string' ? q : ''))
+        .filter((q) => q.length > 0);
+    // Branch on the RENDERED questions, not on `questions.length`: `['']` has
+    // length 1 and collapses to nothing, and a "Questions:" header over no
+    // questions reads as a rendering bug rather than as a script that lost them.
+    if (flat.length === 0) {
+        return '   Questions: none readable in the stored script.';
+    }
+    const shown = flat.slice(0, QUESTION_RENDER_CAP);
+    const lines = shown.map((q, i) => `     ${i + 1}. ${truncate(q, QUESTION_MAX)}`);
+    const dropped = flat.length - shown.length;
+    const more = dropped > 0
+        ? `\n     (${dropped} more in \`structuredContent.interviewScripts\`)`
+        : '';
+    return `   Questions:\n${lines.join('\n')}${more}`;
+}
+/** One ranked script as its own block. */
+function renderScript(script, rank) {
+    const id = safeId(script.hypothesisId);
+    const statement = safeInline(script.statement, STATEMENT_MAX);
+    const whoToAsk = safeInline(script.whoToAsk, WHO_TO_ASK_MAX);
+    // The heading names the hypothesis, because a question set detached from the
+    // hypothesis it serves is the thing this tool exists to stop being handed out.
+    const heading = statement
+        ? `${rank}. ${statement}`
+        : `${rank}. (this run recorded no statement for the hypothesis this script serves)`;
+    const lines = [
+        heading,
+        id
+            ? `   Hypothesis: ${id} — ${verdictClause(script)}`
+            : `   Hypothesis: NOT IDENTIFIED — ${verdictClause(script)}. Without an id these answers ` +
+                'cannot be tied back to a hypothesis.',
+    ];
+    if (whoToAsk)
+        lines.push(`   Who to ask: ${whoToAsk}`);
+    lines.push(questionBlock(script.questions));
+    return lines.join('\n');
+}
+export async function listInterviewScripts(input, deps) {
+    const parsed = ListInterviewScriptsInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new CollectionToolError(`Invalid input — ${formatZodError(parsed.error)}`);
+    }
+    const { project_id: projectId } = parsed.data;
+    const { scripts, sourceRun } = await fetchInterviewScripts(deps, projectId);
+    let text;
+    if (scripts === null) {
+        // ⚠️ THE HONEST EMPTY STATE. "Absent" is not "settled" and it is not "we looked
+        // and there was nothing worth asking". A scoped scan or a failed run leaves a
+        // project with no scripts while its hypotheses are wide open, so this sentence
+        // has to say that nothing is on record rather than imply a finding.
+        text =
+            `No interview scripts recorded for project ${projectId}.\n\n` +
+                'This means NO completed research run has written interview scripts for this project. It ' +
+                'is NOT a finding about the hypotheses: not "they are settled", not "there is nothing ' +
+                'worth asking", not zero. There is simply nothing on record.\n\n' +
+                'This tool never generates scripts — it reads what a run stored, and it will keep ' +
+                'returning this until one exists. Run `clien_research` (a full run) to produce them. ' +
+                '`scan_competitors` and `search_forums` are scoped runs and never write scripts, so ' +
+                'running those will leave this empty.';
+    }
+    else {
+        const runId = safeId(sourceRun?.id ?? null);
+        const when = safeInline(sourceRun?.createdAt ?? null, TIMESTAMP_MAX);
+        if (scripts.length === 0) {
+            // ⚠️ A DIFFERENT FACT FROM THE `null` BRANCH. A run IS on record and it did
+            // write a scripts array — the endpoint only names a run that did. Nothing in
+            // it could be read, which is a defect in the stored report, not a statement
+            // about the hypotheses. Collapsing the two would tell a caller no research
+            // has been done when some has.
+            text =
+                `Project ${projectId} has a research run that wrote interview scripts, and none of ` +
+                    'them could be read.\n\n' +
+                    (runId
+                        ? `Run ${runId}${when ? ` (recorded ${when})` : ''} stored a scripts array whose ` +
+                            'entries are unusable — a malformed report, not an answer about the hypotheses. '
+                        : 'The run that wrote them stored a scripts array whose entries are unusable — a ' +
+                            'malformed report, not an answer about the hypotheses. ') +
+                    'Do not treat this as "nothing worth asking". Read the run itself with `get_report` for ' +
+                    'its hypotheses, or run `clien_research` again to write a fresh set.\n\n' +
+                    provenanceLine(sourceRun?.id ?? null, sourceRun?.createdAt ?? null) +
+                    '\n\n' +
+                    CHANNEL_NOTE;
+        }
+        else {
+            const shown = scripts.slice(0, SCRIPT_RENDER_CAP);
+            const dropped = scripts.length - shown.length;
+            const capNote = dropped > 0
+                ? `\n\n(${dropped} more script${dropped === 1 ? '' : 's'} in ` +
+                    '`structuredContent.interviewScripts`.)'
+                : '';
+            text =
+                `Interview scripts for project ${projectId} — ${scripts.length} script` +
+                    `${scripts.length === 1 ? '' : 's'}` +
+                    `${runId ? ` from research run ${runId}` : ''}${when ? ` (recorded ${when})` : ''}.\n\n` +
+                    'These are the STORED output of that run, written when it ran. Nothing was generated to ' +
+                    'answer this call.\n\n' +
+                    'RANKED least-settled first: the hypothesis nearest a coin flip goes first, because a ' +
+                    'real answer there moves the verdict most. That order is the run\'s, not this ' +
+                    'client\'s.\n\n' +
+                    shown.map((script, i) => renderScript(script, i + 1)).join('\n\n') +
+                    capNote +
+                    '\n\n' +
+                    LINKAGE_LINE +
+                    '\n\n' +
+                    provenanceLine(sourceRun?.id ?? null, sourceRun?.createdAt ?? null) +
+                    '\n\n' +
+                    SCRIPTS_TRUST_LINE +
+                    '\n\n' +
+                    CHANNEL_NOTE;
+        }
+    }
+    return {
+        content: [{ type: 'text', text }],
+        // Both keys are present even when null — the PRESENCE is what tells a
+        // structured consumer "no run has written scripts" apart from "this tool did
+        // not answer".
+        _meta: { interviewScripts: scripts, sourceRun },
+    };
+}
+//# sourceMappingURL=interview-scripts.js.map

package/dist/tools/interview-scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interview-scripts.js","sourceRoot":"","sources":["../../src/tools/interview-scripts.ts"],"names":[],"mappings":"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"}

package/dist/tools/interview.js

@@ -41,8 +41,26 @@ import { z } from 'zod';
 import { ToolError } from './errors.js';
 import { deprecatedAlias } from './param-aliases.js';
 import { apiCall, categorizeFetchError, } from './research.js';
-import { safeBlock, safeInline, safeId, truncate } from './render-safety.js';
+import { safeBlock, safeInline, safeId, truncate, ID_MAX } from './render-safety.js';
 const INTERVIEW_FETCH_TIMEOUT_MS = 60_000;
+/**
+ * The shape a `hypothesis_id` must have to be storable (FUL-577).
+ *
+ * ⚠️ It is `safeId`'s rule, restated as a Zod check rather than re-derived — the
+ * cap IS `ID_MAX` and the character class is the one `safeId` rejects on. That is
+ * not a coincidence to be tidied away: `safeId` is what decides whether the value
+ * can ever be handed BACK to an agent (it returns the input byte-identical or
+ * `null`, never a clipped third thing), so accepting an id it would refuse means
+ * writing something no reader can be shown. Rejecting it at the input boundary is
+ * the difference between a clear parameter error and a value that silently renders
+ * as nothing on every later read.
+ *
+ * The app enforces the same rule at `HYPOTHESIS_ID_REGEX` in
+ * `app/lib/validation/schemas.ts`, and the database again as a CHECK. This copy is
+ * the one that gives the agent the error in the turn it made the mistake.
+ */
+const HYPOTHESIS_ID_MAX = ID_MAX;
+const HYPOTHESIS_ID_REGEX = /^[^\s\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+$/u;
 /** Upper bound on a turn's question — matches the server's `MESSAGE_CONTENT_MAX`. */
 const CONTENT_MAX = 10_000;
 /** FUL-233: legacy camelCase spellings `interview_persona` still accepts. */
@@ -94,6 +112,26 @@ export const InterviewPersonaInputSchema = z.object({
         .describe('action=start: set true for a scratch/throwaway interview that should NOT count toward the ' +
         'project\'s aggregate insights (sets include_in_insights=false). Leave false (the default) ' +
         'for a real interview you want reflected in project-level analysis.'),
+    hypothesis_id: z
+        .string()
+        .max(HYPOTHESIS_ID_MAX)
+        .regex(HYPOTHESIS_ID_REGEX, 'hypothesis_id must be a single token with no spaces')
+        .optional()
+        .describe('action=start: the `hypothesisId` of the `list_interview_scripts` script you are about to ' +
+        'ask, RECORDED ON THE INTERVIEW. Send it with `hypothesis_run_id` (that call\'s ' +
+        '`sourceRun.id`) or not at all — an id alone is ambiguous, because the same "H3" recurs ' +
+        'across runs of one project meaning different things. Optional: omit both for an ' +
+        'interview that tests no particular hypothesis. Once stored it comes back on ' +
+        '`get_interview` and `list_interviews`, so the answers stay tied to the hypothesis ' +
+        'without you carrying the id through the conversation.'),
+    hypothesis_run_id: z
+        .string()
+        .uuid()
+        .optional()
+        .describe('action=start: the research run that defined `hypothesis_id` — `sourceRun.id` from the same ' +
+        '`list_interview_scripts` call. Required whenever `hypothesis_id` is sent, and refused ' +
+        'without it. Recorded as provenance, NOT checked against the run: a run can be deleted ' +
+        'and the interview outlives it.'),
     // --- Deprecated camelCase aliases (FUL-233) — rewritten before parse. ---
     projectId: deprecatedAlias('project_id', z.string().uuid()),
     personaId: deprecatedAlias('persona_id', z.string().uuid()),
@@ -112,8 +150,8 @@ function makeCtx(deps) {
  * insufficient-credit stop with balance/required/buy-url guidance; 401 drops the
  * cached session (so the next tool call rebuilds from disk) and surfaces a
  * re-auth message; 404 means the interview/project isn't owned by the caller;
- * 400 surfaces the server's validation detail; everything else surfaces a
- * generic HTTP error.
+ * 403 with a lock code surfaces the upgrade path; 400 surfaces the server's
+ * validation detail; everything else surfaces a generic HTTP error.
  *
  * FUL-161: the body is read and parsed ONCE up front rather than after the 404
  * branch, because the 402 branch needs its `balance`/`required`/`buy_url` and a
@@ -159,6 +197,22 @@ async function throwForResponse(response, deps, action, options) {
             deps.invalidateSession?.();
         throw new InterviewToolError('Session expired. Re-run any Clien.ai tool to re-authenticate, then try again.');
     }
+    // FUL-503. Without this branch a subscription lock reads as
+    // `Failed to start interview (HTTP 403)` — indistinguishable from a bug, so the
+    // agent retries something no retry can fix. Mirrors `personas.ts`, including
+    // naming the resource that is actually locked.
+    //
+    // FUL-553 widened where these codes come from: `start` was the only action that
+    // could produce them, and now `turn` and `complete`/`reopen` do too, because a
+    // locked project is read-only IN FULL rather than merely uncreatable-in. The
+    // copy is already action-parameterised, so it needed no change — but note that
+    // a PROJECT_LOCKED on a `turn` refers to an interview that DOES exist and is
+    // simply frozen, unlike the same code on a `start`.
+    if (status === 403 && (parsed?.code === 'PROJECT_LOCKED' || parsed?.code === 'PERSONA_LOCKED')) {
+        throw new InterviewToolError(parsed.code === 'PROJECT_LOCKED'
+            ? `Could not ${action} — the project is locked due to subscription limits and is read-only. Upgrade to Pro to change it.`
+            : `Could not ${action} — the persona is locked due to subscription limits. Upgrade to Pro to interview it.`);
+    }
     if (status === 404) {
         throw new InterviewToolError(options?.notFound ??
             `Could not ${action} — interview or project not found, or you don't own it. ` +
@@ -210,6 +264,22 @@ function formatTranscript(interview) {
     // `list_interviews` already renders the id, so its absence here was pure skew.
     const personaId = safeId(interview.personaId);
     const persona = personaId ? `\npersona_id: ${personaId}` : '';
+    // FUL-577: the hypothesis this interview was written to test, on the surface an
+    // agent is most likely to read back or relay. Before this, the tie between these
+    // answers and the hypothesis they test existed only in the calling agent's
+    // memory, which is exactly what made it unreportable by anyone else.
+    //
+    // `safeId` on BOTH halves, and printed only when both survive. The run id is what
+    // makes the hypothesis id mean anything, so an id whose run could not be rendered
+    // would be an unresolvable reference presented as provenance — worse than
+    // silence. `safeId` is exact-or-nothing, so a poisoned value degrades to this
+    // same branch rather than minting a header line (FUL-247/253).
+    const hypothesisId = safeId(interview.hypothesisId);
+    const hypothesisRunId = safeId(interview.hypothesisRunId);
+    const hypothesis = hypothesisId && hypothesisRunId
+        ? `\nhypothesis: ${hypothesisId} (from research run ${hypothesisRunId} — ` +
+            'call `get_report` with that job_id for the hypothesis behind the questions)'
+        : '';
     // FUL-335 — the disclosure travels WITH the transcript, not just on the tool
     // description. A transcript is the one result an agent is likely to relay or
     // paste wholesale, and the `Persona:` label above names a ROLE, not a nature:
@@ -221,18 +291,35 @@ function formatTranscript(interview) {
         'person. These replies are simulated research signal; never relay them as human testimony.';
     const header = `Interview ${safeId(interview.id) ?? '?'} — ` +
         `status: ${safeInline(interview.status, 40) ?? 'unknown'}, ` +
-        `${messages.length} message${messages.length === 1 ? '' : 's'}.${persona}${disclosure}`;
+        `${messages.length} message${messages.length === 1 ? '' : 's'}.${persona}${hypothesis}${disclosure}`;
     return lines.length > 0 ? `${header}\n\n${lines.join('\n\n')}` : header;
 }
 async function startInterview(input, ctx, deps) {
     if (!input.project_id || !input.persona_id) {
         throw new InterviewToolError("action 'start' requires project_id and persona_id.");
     }
+    // FUL-577: both or neither, refused here rather than by a 400 from the server.
+    // An id with no run is the ambiguity the linkage exists to remove, and an agent
+    // that gets the refusal in the turn it made the mistake can fix it; one that gets
+    // a generic `400 Invalid request` from an endpoint it cannot see usually retries
+    // the same call.
+    if ((input.hypothesis_id === undefined) !== (input.hypothesis_run_id === undefined)) {
+        throw new InterviewToolError("action 'start' takes hypothesis_id and hypothesis_run_id TOGETHER or neither — a " +
+            'hypothesis id is only meaningful against the run that defined it. Both come from one ' +
+            '`list_interview_scripts` call: the script\'s `hypothesisId`, and that call\'s ' +
+            '`sourceRun.id`.');
+    }
     const response = await call(ctx, 'POST', '/api/interviews', 'start interview', {
         projectId: input.project_id,
         personaId: input.persona_id,
         withFirstMessage: true,
         ephemeral: input.ephemeral,
+        // Sent only when named. An older app deploy's zod schema STRIPS keys it does
+        // not know, so sending `undefined` and sending nothing are the same request —
+        // which is precisely why the echo below is checked rather than assumed.
+        ...(input.hypothesis_id !== undefined
+            ? { hypothesisId: input.hypothesis_id, hypothesisRunId: input.hypothesis_run_id }
+            : {}),
     });
     if (!response.ok)
         await throwForResponse(response, deps, 'start interview');
@@ -255,13 +342,56 @@ async function startInterview(input, ctx, deps) {
         content: [
             {
                 type: 'text',
-                text: `Started interview ${safeId(interview.id) ?? 'unknown'}${who}.${insightsNote}${greeting}\n` +
+                text: `Started interview ${safeId(interview.id) ?? 'unknown'}${who}.${insightsNote}` +
+                    `${hypothesisNote(input, interview)}${greeting}\n` +
                     "Ask questions with action='turn'; close it with action='complete' when done.",
             },
         ],
         _meta: { interview, personaName: json?.personaName, firstMessageContent: json?.firstMessageContent },
     };
 }
+/**
+ * What `start` says about the hypothesis linkage — CONFIRMED FROM THE ECHO, never
+ * from the fact that we sent it (FUL-577).
+ *
+ * ⚠️ This is the version-skew seam that actually costs something here, and it is on
+ * the WRITE. `@clien-ai/mcp` ships to npm on its own cadence and routinely meets an
+ * app deploy older than itself; that deploy's Zod body schema does not know
+ * `hypothesisId`, and Zod STRIPS unknown keys rather than rejecting them. So the
+ * request succeeds, the interview is created, nothing anywhere reports a problem —
+ * and the linkage this issue exists to store was silently dropped. An agent told
+ * "recorded" then reports its answers as anchored to a hypothesis no row mentions,
+ * which is a worse outcome than the prose instruction this replaced: at least that
+ * one was honest about being unenforced.
+ *
+ * Comparing the round trip is the only check that distinguishes the two, and it
+ * costs nothing — the created interview is already in the response. Silence when
+ * the caller asked for a linkage is not an option: it reads as success.
+ */
+function hypothesisNote(input, interview) {
+    if (input.hypothesis_id === undefined)
+        return '';
+    const storedId = interview.hypothesisId;
+    const storedRunId = interview.hypothesisRunId;
+    // ⚠️ The run id is compared CASE-INSENSITIVELY. Postgres renders a `uuid` lowercase
+    // whatever case it was written in, while both this schema and the route's
+    // `UUID_REGEX` accept an uppercase one — so an agent that pasted `9F2…` would get the
+    // loud "not recorded" warning about a linkage that stored perfectly. The hypothesis id
+    // is `text` and echoes back byte for byte, so it stays an exact comparison.
+    const runIdEchoed = storedRunId != null &&
+        input.hypothesis_run_id != null &&
+        storedRunId.toLowerCase() === input.hypothesis_run_id.toLowerCase();
+    if (storedId === input.hypothesis_id && runIdEchoed) {
+        return (` Recorded against hypothesis ${safeId(storedId) ?? 'unknown'} from research run ` +
+            `${safeId(storedRunId) ?? 'unknown'} — the answers stay tied to it, so you do not have to ` +
+            'carry the id yourself.');
+    }
+    return (' ⚠️ THE HYPOTHESIS LINKAGE WAS NOT RECORDED: the server did not echo back the id this call ' +
+        'sent, which usually means the Clien.ai deploy answering predates the field. The interview ' +
+        'itself is fine and every turn will work. Do NOT report its answers as anchored to that ' +
+        'hypothesis on the strength of this call — nothing stored the tie, so carry the id yourself ' +
+        'if you need it.');
+}
 async function sendTurn(input, ctx, deps) {
     if (!input.interview_id || !input.content) {
         throw new InterviewToolError("action 'turn' requires interview_id and content.");
@@ -530,7 +660,19 @@ export async function listInterviews(input, deps) {
             // off the end of a row.
             const startedAt = safeInline(iv.startedAt, 40);
             const started = startedAt ? ` — started ${startedAt}` : '';
-            return `- ${status} interview${persona} — ${messages}${started} (id: ${safeId(iv.id) ?? 'unknown'})`;
+            // FUL-577: the hypothesis a listed interview was written to test. This is the
+            // surface where it earns the most — "which interviews tested H3?" was a
+            // question nobody could answer from stored data, and the list is where an
+            // agent goes looking. Printed only when BOTH halves render, for the reason
+            // given on `formatTranscript`: an id without its run is an unresolvable
+            // reference dressed as provenance. `safeId` keeps a poisoned value from
+            // forging a sibling `- ` row (FUL-253).
+            const hypothesisId = safeId(iv.hypothesisId);
+            const hypothesisRunId = safeId(iv.hypothesisRunId);
+            const hypothesis = hypothesisId && hypothesisRunId
+                ? ` — tests hypothesis ${hypothesisId} of run ${hypothesisRunId}`
+                : '';
+            return `- ${status} interview${persona} — ${messages}${started}${hypothesis} (id: ${safeId(iv.id) ?? 'unknown'})`;
         });
         const shown = offset + interviews.length;
         const more = shown < total ? `\n\n${total - shown} more not shown — page with offset=${shown}.` : '';