@owlmeans/viable-sdk 0.1.18-rc.21 → 0.1.18-rc.23

package/build/tools/catalogue.js

@@ -1,17 +1,18 @@
 import { z } from 'zod';
 import { CommitTimeout, TransitionAction, WorkcardKind } from '@owlmeans/planning';
-import { ConnectJobKind, ConnectTarget, ConversionDecision, ConversionStatus, ConvertibilityVerdict, decisionFor, jobIdOf, MODEL_TIER_ROLES, OriginKind, STORY_BAND_MAX_USD, STORY_BAND_MIN_USD, VIABLE_STORY_TYPE, ViableStoryTransition } from '@owlmeans/viable-common';
-import { COMMIT_WAIT_MS, JOB_POLL_MAX_SEC, NEXT_QUESTION_WAIT_MS, NEXT_TASK_WAIT_MS, STORY_PAGE_SIZE } from '../consts.js';
+import { ConnectTarget, ConversionDecision, ConversionStatus, ConvertibilityVerdict, MODEL_TIER_ROLES, OriginKind, STORY_BAND_MAX_USD, STORY_BAND_MIN_USD, VIABLE_STORY_TYPE, ViableStoryTransition } from '@owlmeans/viable-common';
+import { COMMIT_WAIT_MS, NEXT_QUESTION_WAIT_MS, NEXT_TASK_WAIT_MS, STORY_PAGE_SIZE } from '../consts.js';
 import { describeHarness, installHarness } from '../harness/index.js';
 import { envStatus } from '../project/env.js';
 import { missingServices, readSetupReport, renderSetupGuide, setUserEnv } from '../project/setup.js';
 import { localStatus, runLocal, stopLocal } from '../run/index.js';
 import { parseTaskResult, renderTaskEnvelope } from '../task/envelope.js';
 import { parseAnswer, renderQuestionEnvelope } from '../task/inquiry.js';
-import { renderJob } from './jobs.js';
-import { PLATFORM_CATALOGUE, renderPlatform } from './platform.js';
+import { GENERATED_SUMMARY, PLATFORM_CATALOGUE, renderPlatform } from './platform.js';
 import { refusalMessage, refusalPhrase } from './refusal.js';
-import { renderStories, resolveStory, STORY_ORDER, storyQuery } from './stories.js';
+import { renderProjectSettings, settingsPatch, settingsReach } from './settings.js';
+import { conversionNext, renderPipelineStatus, renderProjectStatus, renderStoryStatus, } from './status.js';
+import { isLandingStory, renderStories, resolveStory, STORY_ORDER, storyQuery } from './stories.js';
 import { anyHost, cloudTarget, localTarget, performsModelTasks, sessionCapable, ToolHostKind, withExecutor } from './types.js';
 const ok = (text, structured) => ({ text, structured });
 const fail = (text) => ({ text, isError: true });
@@ -72,7 +73,16 @@ const projectOf = (args, deps) => {
     }
     return project;
 };
-const jobResult = (job) => ok(renderJob(job), { job: job });
+const projectResult = (status) => ok(renderProjectStatus(status), { project: status });
+/** A story's domain status, with what its card says that the status route does not carry. */
+const storyResult = (status, card) => {
+    const landing = isLandingStory(card);
+    return ok(renderStoryStatus(status, { landing }), { story: status, ...(landing ? { landing } : {}) });
+};
+/** The project settings, led by what a save just did where one did. */
+const settingsResult = (projectId, settings, lead) => ok((lead != null ? `${lead}\n\n` : '') + renderProjectSettings(projectId, settings), { projectId, settings: settings });
+const pipelineResult = (status) => ok(renderPipelineStatus(status), { pipeline: status });
+const conversionResult = (status) => ok(renderConversion(status), { conversion: status });
 /**
  * Attach a connector, where this host can hold one.
  *
@@ -123,36 +133,35 @@ const waitForStoryCleanup = async (deps, projectId) => {
 /** The project a tool acts on when it can also work without one. */
 const projectOrNull = (args, deps) => typeof args.projectId === 'string' ? args.projectId : deps.attached();
 /**
- * The question a PARKED run is waiting on, when the connector's own queue holds none.
+ * The question a parked domain operation is waiting on, when this session holds none.
  *
  * A question is delivered as an operation and answered against it, and that is the fast path. But
  * an operation expires: a run that asked while nobody was attached, or while this connector was
  * being restarted, is left `Waiting` with a question no queue here has ever seen. Without this the
- * only way back to it is the web application, and a parent polling the job would wait out the
- * whole timeout on a question it could have carried in seconds.
+ * only way back to it is the web application, and a parent watching only the run would wait out the
+ * whole interaction on a question it could have carried in seconds.
  *
  * Best-effort on both reads. A project with no conversion answers an error, and failing the call
  * that asked for a question because the lookup for it failed would be worse than answering "none".
  */
-const parkedQuestion = async (deps, projectId, jobId) => {
+const parkedQuestion = async (deps, projectId) => {
     try {
-        const status = await deps.api.convert.status(projectId);
+        const status = await deps.api.project.status(projectId);
         if (status.pendingInquiry != null)
             return status.pendingInquiry;
     }
     catch (e) {
-        deps.log(`no conversion question for ${projectId}: ${e.message}`);
+        deps.log(`no project question for ${projectId}: ${e.message}`);
     }
-    if (jobId == null)
-        return null;
     try {
-        const job = await deps.api.project.job(projectId, jobId);
-        return job.inquiry ?? null;
+        const status = await deps.api.convert.status(projectId);
+        if (status.pendingInquiry != null)
+            return status.pendingInquiry;
     }
     catch (e) {
-        deps.log(`no question on job ${jobId}: ${e.message}`);
-        return null;
+        deps.log(`no conversion question for ${projectId}: ${e.message}`);
     }
+    return null;
 };
 const questionResult = (inquiry, deps, note) => ok((note != null ? `${note}\n\n` : '') + renderQuestionEnvelope(inquiry, { harness: deps.host.harness }), { questionId: inquiry.id });
 /** A cost estimate, always with the sentence that says what it is not. */
@@ -237,7 +246,7 @@ const renderCheck = (check, conversion) => {
         ? 'nothing — this origin cannot be converted'
         : conversion != null
             ? conversionNext(conversion)
-            : 'convert_project to start, then poll the job with wait_for'}`);
+            : 'convert_project to start, then read conversion_status'}`);
     return lines.join('\n');
 };
 const renderConversion = (view) => {
@@ -264,47 +273,20 @@ const renderConversion = (view) => {
             + ` $${STORY_BAND_MIN_USD}–$${STORY_BAND_MAX_USD} each.`);
     }
     // Phrased, exactly like a thrown one: the platform writes a failed stage's cause here with
-    // `describeFailure`, which for a refusal is the marker verbatim — so a conversion stopped by a
-    // declined relocation answered this tool with `viable-agent-common:conversion:relocate-declined`
-    // while `wait_for` on the very same run read out the sentence. One refusal, two readings.
+    // `describeFailure`, which for a refusal is the marker verbatim. Phrase the stored value the
+    // same way as a thrown refusal so every conversion status has one user-facing reading.
     if (view.lastError != null && view.lastError !== '') {
         lines.push(`error: ${refusalPhrase(view.lastError)}`);
     }
     lines.push(`next: ${conversionNext(view)}`);
     return lines.join('\n');
 };
-/**
- * What to call after reading a conversion.
- *
- * Derived from the STATUS first and the stage second, because the two say different things: a
- * stage says how far the conversion has got, and only the status says whether the platform is
- * working, waiting for a person, or waiting for a decision that is the user's.
- */
-const conversionNext = (view) => {
-    switch (view.status) {
-        case ConversionStatus.Running:
-            return 'wait_for on the job, or conversion_status again';
-        case ConversionStatus.Waiting:
-            return 'next_question — this conversion needs a decision from the person you work for';
-        case ConversionStatus.Awaiting:
-            return `proceed_conversion { "decision": "${decisionFor(view.stage)}" } to go on, or`
-                + ` { "decision": "${ConversionDecision.Leave}" } to keep what it has produced`;
-        case ConversionStatus.Failed:
-            return `proceed_conversion { "decision": "${ConversionDecision.Retry}" } once the cause is addressed`;
-        case ConversionStatus.Done:
-            return 'nothing — this conversion is finished. purge_origin deletes the original sources.';
-        case ConversionStatus.Cancelled:
-            return 'nothing — this conversion was cancelled';
-        default:
-            return 'convert_project to start it';
-    }
-};
 /**
  * Everything a parent agent can ask the platform to do.
  *
  * Two rules shape the whole list. Every tool answers inside the strictest host's per-tool ceiling,
- * so anything that takes minutes returns a JOB at once and is polled — a coding agent that blocks
- * for twenty minutes is reported to its user as a hung server. And every tool that cannot work in
+ * so anything that takes minutes returns its current domain status and continues server-side. And
+ * every tool that cannot work in
  * a given mode is HIDDEN rather than failing, so the catalogue a parent reads is exactly the set
  * of things that work for it.
  */
@@ -313,9 +295,9 @@ export const catalogue = [
         name: 'describe_platform',
         title: 'What this platform can build, and what you can drive from here',
         description: 'Everything the platform runs — building an application from a description, implementing'
-            + ' user stories, converting an application you already have — and which of it this session'
-            + ' can start. Read it before deciding how to approach a request. Needs no project and'
-            + ' makes no network call.',
+            + ' user stories, converting an application you already have — what every application it'
+            + ' generates carries, and which of it this session can start. Read it before deciding how to'
+            + ' approach a request. Needs no project and makes no network call.',
         input: {},
         availability: anyHost,
         run: async (_args, deps) => ok(renderPlatform(PLATFORM_CATALOGUE, deps.host)),
@@ -324,7 +306,8 @@ export const catalogue = [
         name: 'describe_capabilities',
         title: 'Report what your models can do',
         description: 'Tell the platform which of your models it may use, so it can size each call. Call this once,'
-            + ' before creating or developing anything. Returns the mapping it will use.',
+            + ' before creating or developing anything. Returns the mapping it will use, and what every'
+            + ' generated application carries.',
         input: {
             strong: z.string().optional().describe('Your most capable model, e.g. the one you plan with'),
             standard: z.string().optional().describe('Your everyday model'),
@@ -351,7 +334,8 @@ export const catalogue = [
                 return ok('No model was recorded: this tool takes `strong`, `standard` and `cheap` as TOP-LEVEL'
                     + ' string arguments, not nested under another key. The platform will size every call'
                     + ' with its own defaults until you send them.\n\n'
-                    + roleSummary(), { tiers, roles: rolesByTier() });
+                    + roleSummary()
+                    + `\n\n${GENERATED_SUMMARY}`, { tiers, roles: rolesByTier() });
             }
             const byTier = rolesByTier();
             return ok('Recorded. The platform asks for three power classes:\n'
@@ -364,13 +348,14 @@ export const catalogue = [
                 // a delegated session performs all of them, an ordinary one performs a conversion's. Both
                 // collect them the same way, so both are told to call next_task.
                 + (performsModelTasks(deps.host)
-                    ? '\n\nThis session runs the platform\'s model calls on YOUR side. Whenever a job reports'
-                        + ' "blocked on: model-task", call next_task.'
+                    ? '\n\nThis session runs the platform\'s model calls on YOUR side. Whenever a domain status'
+                        + ' reports waiting for a model task, call next_task.'
                     : sessionCapable(deps.host)
                         ? '\n\nThe platform performs its own model calls for stories and free flight. A'
-                            + ' CONVERSION\'s calls are yours by default. Whenever a job reports "blocked on:'
-                            + ' model-task", call next_task.'
-                        : ''), { tiers, subagents, effortControl, roles: byTier });
+                            + ' CONVERSION\'s calls are yours by default. Whenever a domain status reports'
+                            + ' waiting for a model task, call next_task.'
+                        : '')
+                + `\n\n${GENERATED_SUMMARY}`, { tiers, subagents, effortControl, roles: byTier });
         },
     },
     {
@@ -438,36 +423,17 @@ export const catalogue = [
             return ok(lines.join('\n'));
         },
     },
-    {
-        name: 'wait_for',
-        title: 'Wait for a job',
-        description: `Poll one job for up to ${JOB_POLL_MAX_SEC} seconds. Returns as soon as it finishes or`
-            + ' becomes blocked; call again while it is still running.',
-        input: {
-            jobId: z.string(),
-            projectId: z.string().optional(),
-            maxWaitSec: z.number().int().min(0).max(JOB_POLL_MAX_SEC).optional(),
-        },
-        availability: anyHost,
-        run: async (args, deps) => {
-            const project = projectOf(args, deps);
-            const wait = Math.min(args.maxWaitSec ?? JOB_POLL_MAX_SEC, JOB_POLL_MAX_SEC);
-            const job = await deps.api.project.job(project, args.jobId, wait);
-            return jobResult(job);
-        },
-    },
     {
         name: 'create_project',
         title: 'Start a project from a description',
         description: 'Describe the application in a sentence or two. The platform writes a specification, names it'
-            + ' and drafts a vision. Returns a job — poll it with wait_for, then read the draft and call'
-            + ' confirm_project.',
+            + ' and drafts a vision. Returns the project status; read the draft and call confirm_project.',
         input: { prompt: z.string().min(1) },
         availability: anyHost,
         run: async (args, deps) => {
-            const job = await deps.api.project.create(args.prompt, deps.host.target === ConnectTarget.Local ? ConnectTarget.Local : ConnectTarget.Cloud);
-            deps.attach(job.projectId);
-            return jobResult(job);
+            const status = await deps.api.project.create(args.prompt, deps.host.target === ConnectTarget.Local ? ConnectTarget.Local : ConnectTarget.Cloud);
+            deps.attach(status.project.id);
+            return projectResult(status);
         },
     },
     {
@@ -475,7 +441,7 @@ export const catalogue = [
         title: 'Accept the specification and build the application',
         description: 'Confirm the drafted project, optionally editing what the analysis produced. This is what'
             + ' starts the build: the template lands, dependencies install, the whole application is'
-            + ' drawn. Returns a job — it takes several minutes.',
+            + ' drawn. Returns the project status while the server-side run continues.',
         input: {
             projectId: z.string().optional(),
             name: z.string().optional(),
@@ -492,14 +458,14 @@ export const catalogue = [
             // whose connector has not filed a session yet is not queued for later — a local target
             // answers it with `ConnectSessionGone` and the step fails.
             await ensureSession(deps, project);
-            const job = await deps.api.project.confirm(project, {
+            const status = await deps.api.project.confirm(project, {
                 ...(typeof args.name === 'string' ? { name: args.name } : {}),
                 ...(typeof args.description === 'string' ? { description: args.description } : {}),
                 ...(typeof args.specification === 'string' ? { specification: args.specification } : {}),
                 ...(typeof args.vision === 'string' ? { vision: args.vision } : {}),
                 ...(typeof args.designSystem === 'string' ? { designSystem: args.designSystem } : {}),
             });
-            return jobResult(job);
+            return projectResult(status);
         },
     },
     {
@@ -598,14 +564,63 @@ export const catalogue = [
         run: async (args, deps) => {
             const project = projectOf(args, deps);
             await ensureSession(deps, project);
-            const job = await deps.api.project.reinit(project);
-            return jobResult(job);
+            return projectResult(await deps.api.project.reinit(project));
+        },
+    },
+    {
+        name: 'project_settings',
+        title: 'The project\'s settings',
+        description: 'The settings a person edits on the project\'s control panel: the copyright line, the'
+            + ' organization name, the Terms and Privacy links, and the Google tag. A relative link such'
+            + ' as /terms or /privacy is normal — it is the page the platform generated inside the'
+            + ' application, and the generated pages name the organization and copyright set here.',
+        input: { projectId: z.string().optional() },
+        availability: anyHost,
+        run: async (args, deps) => {
+            const project = projectOf(args, deps);
+            return settingsResult(project, await deps.api.projectBranding(project));
         },
     },
+    {
+        name: 'update_project_settings',
+        title: 'Change the project\'s settings',
+        description: 'Change any of the copyright line, the organization name, the Terms and Privacy links and the'
+            + ' Google tag; whatever you leave out keeps its value. Copyright and organization are never'
+            + ' empty. A legal link is an https:// address or a path on the application itself — /terms'
+            + ' and /privacy are the generated pages. A Google tag is a GTM-, G-, GT-, AW- or DC- id, or'
+            + ' an empty string to remove it; it loads on the preview and in production behind the cookie'
+            + ' consent. The preview is rebuilt with the change; production takes it at the next Publish.',
+        input: {
+            projectId: z.string().optional(),
+            copyright: z.string().optional().describe('The copyright line, e.g. "© 2026 Acme Ltd"'),
+            organizationName: z.string().optional().describe('Who runs the application'),
+            termsUrl: z.string().optional().describe('https://… or a path such as /terms'),
+            privacyUrl: z.string().optional().describe('https://… or a path such as /privacy'),
+            googleTag: z.string().optional()
+                .describe('GTM-XXXXXXX, G-XXXXXXXXXX, GT-…, AW-… or DC-…; an empty string removes it'),
+        },
+        availability: anyHost,
+        run: async (args, deps) => await answering(deps, 'update_project_settings', async () => {
+            const project = projectOf(args, deps);
+            const patch = settingsPatch(args);
+            const changed = Object.keys(patch);
+            if (changed.length < 1) {
+                return fail('Nothing to change. Give at least one of copyright, organizationName, termsUrl, privacyUrl'
+                    + ' or googleTag — project_settings shows the current values.');
+            }
+            // The save ends in a configuration push, and for a local project that push is an operation
+            // THIS connector answers — so it is attached before the platform is asked, exactly as a story
+            // mutation is. A host that holds no session skips it and the platform delivers the push itself.
+            await ensureSession(deps, project);
+            const saved = await deps.api.saveProjectBranding(project, patch);
+            return settingsResult(project, saved, `Saved ${changed.join(', ')}. ${settingsReach(deps.host.target)}`);
+        }),
+    },
     {
         name: 'list_stories',
         title: 'The user stories of a project',
-        description: 'One page of the project\'s stories, with their status.',
+        description: 'One page of the project\'s stories, with their status, the primary story, and the landing'
+            + ' gate story a guest starts on the guest home.',
         input: {
             projectId: z.string().optional(),
             page: z.number().int().min(0).optional(),
@@ -656,7 +671,7 @@ export const catalogue = [
             const project = projectOf(args, deps);
             // Formatting reads the target's file-backed entities before it persists the story. A local
             // project therefore needs its connector back after an MCP restart even though this tool does
-            // not itself return a long-running job.
+            // not itself start a long-running operation.
             await ensureSession(deps, project);
             // The narrative goes as written and with no area: rewriting it and deciding the area is the
             // platform's, done on the way in for a person's story — a connector that guessed an area
@@ -724,7 +739,7 @@ export const catalogue = [
         name: 'develop_story',
         title: 'Implement a user story',
         description: 'Ask the platform to design and build one story: its screens, its data, its endpoints, its'
-            + ' navigation. This is the main event and takes many minutes. Returns a job.',
+            + ' navigation. This is the main event and takes many minutes. Returns the story status.',
         input: { storyId: z.string(), projectId: z.string().optional() },
         availability: anyHost,
         run: async (args, deps) => {
@@ -745,40 +760,38 @@ export const catalogue = [
             catch (e) {
                 if (!(e instanceof CommitTimeout))
                     throw e;
-                // The move is durable and only its commit is late, so the job row is still the answer —
+                // The move is durable and only its commit is late, so the story status is still the answer —
                 // waiting out the host's ceiling here would report a slow platform as a broken server.
                 deps.log(`develop_story: the start of ${card.code ?? card.id} has not committed yet;`
-                    + ' answering from the job');
+                    + ' answering from story status');
             }
-            return jobResult(await deps.api.project.job(project, jobIdOf(ConnectJobKind.StoryDevelop, project, card.id)));
+            return storyResult(await deps.api.story.status(project, card.id), card);
         },
     },
     {
         name: 'story_status',
         title: 'What happened to a story',
-        description: 'One story: its status, and the warning explaining a failure.',
+        description: 'One story, its development run, any warning explaining a failure, and whether it is the'
+            + ' project\'s landing gate story — the one a guest starts on the guest home.',
         input: { storyId: z.string(), projectId: z.string().optional() },
         availability: anyHost,
         run: async (args, deps) => {
-            const card = await resolveStory(deps, projectOf(args, deps), args.storyId);
-            // A warning is cleared by writing it empty, so an empty one is no warning at all.
-            const warning = card.fields?.warning;
-            return ok(`${card.code ?? card.id} · ${card.status}`
-                + (warning != null && warning !== '' ? `\nwarning: ${String(warning)}` : ''), card);
+            const project = projectOf(args, deps);
+            const card = await resolveStory(deps, project, args.storyId);
+            return storyResult(await deps.api.story.status(project, card.id), card);
         },
     },
     {
         name: 'modify_project',
         title: 'Ask the agent for an open-ended change',
         description: 'Describe a change in words and let the platform\'s own coding agent make it. For anything'
-            + ' that is not a user story: a rename, a fix, a styling change. Returns a job.',
+            + ' that is not a user story: a rename, a fix, a styling change. Returns project status.',
         input: { prompt: z.string().min(1), projectId: z.string().optional() },
         availability: anyHost,
         run: async (args, deps) => {
             const project = projectOf(args, deps);
             await ensureSession(deps, project);
-            const job = await deps.api.project.modify(project, args.prompt);
-            return jobResult(job);
+            return projectResult(await deps.api.project.modify(project, args.prompt));
         },
     },
     {
@@ -789,10 +802,7 @@ export const catalogue = [
         availability: anyHost,
         run: async (args, deps) => {
             const state = await deps.api.pipeline.state(projectOf(args, deps), args.runId);
-            return ok(`${String(state.pipeline)} · ${String(state.status)}`
-                + (state.step != null ? ` · stopped at ${String(state.step)}` : '')
-                // A run stops on the same refusals a call is thrown, and the row keeps the cause as text.
-                + (state.error != null ? `\nerror: ${refusalPhrase(String(state.error))}` : ''), state);
+            return pipelineResult(state);
         },
     },
     {
@@ -809,10 +819,10 @@ export const catalogue = [
         run: async (args, deps) => {
             const project = projectOf(args, deps);
             await ensureSession(deps, project);
-            const job = await deps.api.pipeline.resume(project, args.runId, {
+            const status = await deps.api.pipeline.resume(project, args.runId, {
                 ...(typeof args.from === 'string' ? { from: args.from } : {}),
             });
-            return jobResult(job);
+            return pipelineResult(status);
         },
     },
     {
@@ -820,8 +830,8 @@ export const catalogue = [
         title: 'Get the next model call to perform',
         description: 'The platform hands you model calls to perform: a conversion\'s by default, and everything'
             + ' else when this session runs in the delegated mode. Returns one task with instructions for'
-            + ' running it in a clean subagent, or says there is nothing yet. Call it whenever a job'
-            + ' reports "blocked on: model-task", and keep calling until it says none.',
+            + ' running it in a clean subagent, or says there is nothing yet. Call it whenever a domain'
+            + ' status says it is waiting for a model task, and keep calling until it says none.',
         input: {
             maxWaitSec: z.number().int().min(0).max(45).optional(),
             taskId: z.string().optional()
@@ -837,7 +847,7 @@ export const catalogue = [
             // Asking for one by id re-reads it rather than taking a new one. A task is handed out once
             // and the platform waits on it for up to 45 minutes, so a parent that lost the envelope —
             // a compacted conversation, a subagent that died before answering — otherwise has no way
-            // back to it and the job blocks until the deadline for no reason.
+            // back to it and the run waits until the deadline for no reason.
             if (typeof args.taskId === 'string') {
                 const known = session.taskById(args.taskId);
                 if (known == null) {
@@ -856,8 +866,8 @@ export const catalogue = [
                         + ` ${outstanding.map(one => one.id).join(', ')}. Submit the answer with`
                         + ' submit_task_result, or call next_task with that taskId to read it again.');
                 }
-                return ok('No task right now. If a job is still running, call wait_for; if it reported'
-                    + ' "blocked on: model-task", call next_task again.');
+                return ok('No task right now. Read the matching project, story, conversion, or pipeline status;'
+                    + ' call next_task again only while it reports waiting for a model task.');
             }
             return ok(renderTaskEnvelope(task, { harness: deps.host.harness }), { taskId: task.id });
         },
@@ -889,20 +899,18 @@ export const catalogue = [
             const next = session.pendingTasks();
             return ok(next > 0
                 ? `Accepted. ${next} more task(s) waiting — call next_task.`
-                : 'Accepted. Call wait_for on the job, or next_task if it is still blocked.');
+                : 'Accepted. Read the matching project, story, conversion, or pipeline status.');
         },
     },
     {
         name: 'next_question',
         title: 'Get the question the platform is asking',
         description: 'The platform sometimes needs a decision only the person you are working for can make.'
-            + ' Returns one question to put to them, or says there is none. Call it whenever a job'
-            + ' reports "blocked on: question".',
+            + ' Returns one question to put to them, or says there is none. Domain status responses also'
+            + ' include parked questions directly.',
         input: {
             maxWaitSec: z.number().int().min(0).max(45).optional(),
             questionId: z.string().optional().describe('Re-read a question you were already given.'),
-            jobId: z.string().optional()
-                .describe('The job that reported "blocked on: question", if you have its id.'),
             projectId: z.string().optional(),
         },
         // Not `performsModelTasks`: a question has nothing to do with who performs the model calls,
@@ -912,12 +920,11 @@ export const catalogue = [
         run: async (args, deps) => {
             const session = await deps.session();
             const project = projectOrNull(args, deps);
-            const jobId = typeof args.jobId === 'string' ? args.jobId : undefined;
             // Asking for one by id re-reads it rather than taking a new one — the same reason
             // `next_task` does: a parent that lost the envelope has no other way back to it.
             if (typeof args.questionId === 'string') {
                 const known = session.questionById(args.questionId)
-                    ?? (project != null ? await parkedQuestion(deps, project, jobId) : null);
+                    ?? (project != null ? await parkedQuestion(deps, project) : null);
                 if (known == null || known.id !== args.questionId) {
                     return fail(`No question ${args.questionId} is waiting. Call next_question with no id.`);
                 }
@@ -935,12 +942,12 @@ export const catalogue = [
             }
             // Nothing queued here, which does not mean nothing is being asked: a run that parked while
             // this connector was away is waiting on a question whose operation has long expired.
-            const parked = project != null ? await parkedQuestion(deps, project, jobId) : null;
+            const parked = project != null ? await parkedQuestion(deps, project) : null;
             if (parked != null) {
                 return questionResult(parked, deps, 'This run parked on a question before this session attached. It is still open:');
             }
-            return ok('No question right now. If a job is still running, call wait_for; if it reported'
-                + ' "blocked on: question", call next_question again.');
+            return ok('No question right now. Read the matching domain status and answer any pendingInquiry it'
+                + ' returns; call next_question again only while it reports waiting for a person.');
         },
     },
     {
@@ -954,11 +961,6 @@ export const catalogue = [
             answer: z.union([z.string(), z.array(z.string())]).optional(),
             text: z.string().optional().describe('What they said, where the question takes words.'),
             declined: z.boolean().optional().describe('Nobody could decide this.'),
-            // Taken here for the same reason `next_question` takes it, and it has to be the SAME reach:
-            // a question this tool cannot find is refused after a person has already answered it, and
-            // the parent is sent back to `next_question`, which would offer it again through the job.
-            jobId: z.string().optional()
-                .describe('The job that reported "blocked on: question", if you have its id.'),
             projectId: z.string().optional(),
         },
         availability: sessionCapable,
@@ -966,11 +968,10 @@ export const catalogue = [
             const session = await deps.session();
             const questionId = args.questionId;
             const project = projectOrNull(args, deps);
-            const jobId = typeof args.jobId === 'string' ? args.jobId : undefined;
             // The question this session is holding, if it still is. That is what decides HOW the answer
             // travels: an operation the platform is waiting on, or the question's own id.
             const held = session.questionById(questionId);
-            const inquiry = held ?? (project != null ? await parkedQuestion(deps, project, jobId) : null);
+            const inquiry = held ?? (project != null ? await parkedQuestion(deps, project) : null);
             if (inquiry == null || inquiry.id !== questionId) {
                 return fail(`No question ${questionId} is waiting. Call next_question for the current one.`);
             }
@@ -989,7 +990,7 @@ export const catalogue = [
                 }
                 await deps.api.inquiry.answer(project, questionId, answer);
             }
-            return ok('Recorded. Call wait_for on the job.');
+            return ok('Recorded. Read the matching project, story, conversion, or pipeline status.');
         },
     },
     {
@@ -1018,7 +1019,7 @@ export const catalogue = [
         title: 'Convert an application you already have',
         description: 'Bring an existing application onto the platform: it reads the code, restores the'
             + ' specification and the user stories nobody wrote down, and rebuilds it on the platform\'s'
-            + ' stack. The original is kept beside it. Returns a job, and stops at your decision after'
+            + ' stack. The original is kept beside it. Returns conversion status and stops at your decision after'
             + ' each stage.',
         input: {
             projectId: z.string().optional().describe('Convert into a project that already exists.'),
@@ -1033,7 +1034,7 @@ export const catalogue = [
             const named = typeof args.projectId === 'string' ? args.projectId : deps.attached();
             if (named != null) {
                 await ensureSession(deps, named);
-                return jobResult(await deps.api.convert.start(named));
+                return conversionResult(await deps.api.convert.start(named));
             }
             const repoUrl = typeof args.repoUrl === 'string' && args.repoUrl.trim() !== ''
                 ? args.repoUrl.trim()
@@ -1042,7 +1043,7 @@ export const catalogue = [
                 return fail('Nothing to convert. Name a project, attach one, run the connector in the directory you'
                     + ' want converted, or give a repoUrl.');
             }
-            const job = await deps.api.convert.create({
+            const status = await deps.api.convert.create({
                 ...(typeof args.name === 'string' ? { name: args.name } : {}),
                 ...(typeof args.about === 'string' ? { about: args.about } : {}),
                 // A NAMED repository outranks the directory this connector runs in. A stdio connector
@@ -1062,9 +1063,9 @@ export const catalogue = [
                         },
                     }),
             });
-            deps.attach(job.projectId);
-            await ensureSession(deps, job.projectId);
-            return jobResult(await deps.api.convert.start(job.projectId));
+            deps.attach(status.projectId);
+            await ensureSession(deps, status.projectId);
+            return conversionResult(await deps.api.convert.start(status.projectId));
         }),
     },
     {
@@ -1072,7 +1073,7 @@ export const catalogue = [
         title: 'Decide what a conversion does next',
         description: 'A conversion stops after each stage and waits for a decision: analyze what was read,'
             + ' extract the user stories, implement them, leave it as it stands, retry a stage that'
-            + ' failed, or cancel. Returns a job for anything that runs.',
+            + ' failed, or cancel. Returns the conversion status.',
         input: {
             decision: z.enum(Object.values(ConversionDecision)),
             projectId: z.string().optional(),
@@ -1082,8 +1083,8 @@ export const catalogue = [
         run: async (args, deps) => await answering(deps, 'proceed_conversion', async () => {
             const project = projectOf(args, deps);
             await ensureSession(deps, project);
-            const job = await deps.api.convert.proceed(project, args.decision, typeof args.note === 'string' ? args.note : undefined);
-            return jobResult(job);
+            const status = await deps.api.convert.proceed(project, args.decision, typeof args.note === 'string' ? args.note : undefined);
+            return conversionResult(status);
         }),
     },
     {
@@ -1117,7 +1118,7 @@ export const catalogue = [
             }
             const project = projectOf(args, deps);
             await ensureSession(deps, project);
-            return jobResult(await deps.api.convert.purge(project));
+            return conversionResult(await deps.api.convert.purge(project));
         }),
     },
     {