@sellable/mcp 0.1.110 → 0.1.112

package/dist/tools/campaigns.d.ts

@@ -9,6 +9,7 @@ declare const LEAD_SOURCE_PROVIDERS: {
 };
 type LeadSourceProvider = (typeof LEAD_SOURCE_PROVIDERS)[keyof typeof LEAD_SOURCE_PROVIDERS];
 export declare function buildWatchUrl(config: Pick<ReturnType<typeof getConfig>, "apiUrl" | "token" | "activeWorkspaceId" | "workspaceId">, path: string): string;
+export declare function getCampaignBuilderWatchModeParam(): "claude" | "codex";
 export interface Campaign {
     id: string;
     name: string;
@@ -124,6 +125,7 @@ export interface CreateCampaignInput {
     campaignBrief?: string;
     messageGenerationMode?: "template" | "ai-generated";
     currentStep?: string | null;
+    watchNarration?: unknown;
     leadSourceType?: string | null;
     leadSourceProvider?: LeadSourceProvider | "apollo" | null;
     selectedLeadListId?: string | null;
@@ -137,6 +139,7 @@ export interface UpdateCampaignInput {
     leadSourceProvider?: LeadSourceProvider | "apollo" | null;
     selectedLeadListId?: string | null;
     currentStep?: string | null;
+    watchNarration?: unknown;
     interactionMode?: InteractionMode;
     enableICPFilters?: boolean | null;
     useMessagingTemplate?: boolean | null;
@@ -165,6 +168,7 @@ export declare const campaignToolDefinitions: ({
             campaignBrief?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;
@@ -200,6 +204,7 @@ export declare const campaignToolDefinitions: ({
             campaignBrief?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;
@@ -278,6 +283,7 @@ export declare const campaignToolDefinitions: ({
             campaignBrief?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;
@@ -330,6 +336,41 @@ export declare const campaignToolDefinitions: ({
                 type: string[];
                 description: string;
             };
+            watchNarration: {
+                type: string;
+                description: string;
+                properties: {
+                    stage: {
+                        type: string;
+                        enum: string[];
+                    };
+                    headline: {
+                        type: string;
+                    };
+                    visibleState: {
+                        type: string;
+                    };
+                    agentIntent: {
+                        type: string;
+                    };
+                    nextAction: {
+                        type: string[];
+                    };
+                    safety: {
+                        type: string[];
+                    };
+                    progressLabel: {
+                        type: string[];
+                    };
+                    blockedReason: {
+                        type: string[];
+                    };
+                    workerStatuses: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
             leadSourceType: {
                 type: string[];
                 description: string;
@@ -399,6 +440,41 @@ export declare const campaignToolDefinitions: ({
                 type: string[];
                 description: string;
             };
+            watchNarration: {
+                type: string;
+                description: string;
+                properties: {
+                    stage: {
+                        type: string;
+                        enum: string[];
+                    };
+                    headline: {
+                        type: string;
+                    };
+                    visibleState: {
+                        type: string;
+                    };
+                    agentIntent: {
+                        type: string;
+                    };
+                    nextAction: {
+                        type: string[];
+                    };
+                    safety: {
+                        type: string[];
+                    };
+                    progressLabel: {
+                        type: string[];
+                    };
+                    blockedReason: {
+                        type: string[];
+                    };
+                    workerStatuses: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
             interactionMode: {
                 type: string;
                 enum: string[];
@@ -466,6 +542,7 @@ export declare const campaignToolDefinitions: ({
             offerPositioning?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;

package/dist/tools/campaigns.js

@@ -21,10 +21,20 @@ function normalizeLeadSourceProvider(input) {
 }
 export function buildWatchUrl(config, path) {
     const workspaceId = config.activeWorkspaceId || config.workspaceId;
-    const workspaceParam = workspaceId
-        ? `&workspaceId=${encodeURIComponent(workspaceId)}`
-        : "";
-    return `${config.apiUrl}/auth/continue?token=${encodeURIComponent(config.token)}&redirect=${encodeURIComponent(path)}${workspaceParam}`;
+    const url = new URL(path, config.apiUrl);
+    if (workspaceId && !url.searchParams.has("workspaceId")) {
+        url.searchParams.set("workspaceId", workspaceId);
+    }
+    return url.toString();
+}
+export function getCampaignBuilderWatchModeParam() {
+    const explicit = process.env.SELLABLE_WATCH_MODE_DRIVER?.trim().toLowerCase();
+    if (explicit === "claude" || explicit === "codex")
+        return explicit;
+    return process.env.CODEX_HOME ? "codex" : "claude";
+}
+function buildCampaignBuilderWatchPath(campaignId) {
+    return `/campaign-builder/${campaignId}?mode=${getCampaignBuilderWatchModeParam()}`;
 }
 function isLinkedInProfileUrl(input) {
     try {
@@ -175,6 +185,31 @@ export const campaignToolDefinitions = [
                     type: ["string", "null"],
                     description: "Workflow step ID (headless or UI step ID such as filter-rules)",
                 },
+                watchNarration: {
+                    type: "object",
+                    description: "Single structured watch-guide narration object to send with currentStep changes. Include stage, headline, visibleState, agentIntent, and nextAction so the browser guide mirrors Codex progress.",
+                    properties: {
+                        stage: {
+                            type: "string",
+                            enum: [
+                                "brief-review",
+                                "find-leads",
+                                "review-batch",
+                                "fit-message",
+                                "review-ready",
+                            ],
+                        },
+                        headline: { type: "string" },
+                        visibleState: { type: "string" },
+                        agentIntent: { type: "string" },
+                        nextAction: { type: ["string", "null"] },
+                        safety: { type: ["string", "null"] },
+                        progressLabel: { type: ["string", "null"] },
+                        blockedReason: { type: ["string", "null"] },
+                        workerStatuses: { type: "object" },
+                    },
+                    required: ["stage", "headline", "visibleState", "agentIntent"],
+                },
                 leadSourceType: {
                     type: ["string", "null"],
                     description: "Lead source type (existing | new)",
@@ -243,10 +278,35 @@ export const campaignToolDefinitions = [
                     type: ["string", "null"],
                     description: "Headless workflow step ID",
                 },
+                watchNarration: {
+                    type: "object",
+                    description: "Single structured watch-guide narration object to send with currentStep changes. Include stage, headline, visibleState, agentIntent, and nextAction so the browser guide mirrors Codex progress. Do not send separate guideHeadline/guideBody fields.",
+                    properties: {
+                        stage: {
+                            type: "string",
+                            enum: [
+                                "brief-review",
+                                "find-leads",
+                                "review-batch",
+                                "fit-message",
+                                "review-ready",
+                            ],
+                        },
+                        headline: { type: "string" },
+                        visibleState: { type: "string" },
+                        agentIntent: { type: "string" },
+                        nextAction: { type: ["string", "null"] },
+                        safety: { type: ["string", "null"] },
+                        progressLabel: { type: ["string", "null"] },
+                        blockedReason: { type: ["string", "null"] },
+                        workerStatuses: { type: "object" },
+                    },
+                    required: ["stage", "headline", "visibleState", "agentIntent"],
+                },
                 interactionMode: {
                     type: "string",
                     enum: ["step-by-step", "autonomous", "ask-when-needed"],
-                    description: "Execution style for lead sourcing steps (step-by-step | autonomous | ask-when-needed).",
+                    description: "Execution style for Find Leads steps (step-by-step | autonomous | ask-when-needed).",
                 },
                 enableICPFilters: {
                     type: ["boolean", "null"],
@@ -334,7 +394,7 @@ export async function getCampaign(campaignId) {
         api.get(`/api/v3/mcp/campaigns/${campaignId}`),
         fetchCampaignRubrics(campaignId).catch(() => null),
     ]);
-    const watchUrl = buildWatchUrl(config, `/campaign-builder/${campaignId}?mode=claude`);
+    const watchUrl = buildWatchUrl(config, buildCampaignBuilderWatchPath(campaignId));
     // Merge rubrics into campaignOffer
     const rubrics = (rubricsResult?.rubrics || []).map((r) => ({
         id: r.id || "",
@@ -589,7 +649,7 @@ export async function createCampaign(input) {
     // Idempotent resume path
     if (input.campaignId) {
         const existing = await api.get(`/api/v2/campaign-offers/${input.campaignId}`);
-        const watchUrl = buildWatchUrl(config, `/campaign-builder/${existing.id}?mode=claude`);
+        const watchUrl = buildWatchUrl(config, buildCampaignBuilderWatchPath(existing.id));
         const hasCreateFields = input.name ||
             input.clientProspectId ||
             input.offerPositioning !== undefined ||
@@ -707,7 +767,7 @@ export async function createCampaign(input) {
         },
     };
     const result = await api.post(`/api/v2/campaign-offers`, formattedInput);
-    const watchUrl = buildWatchUrl(config, `/campaign-builder/${result.id}?mode=claude`);
+    const watchUrl = buildWatchUrl(config, buildCampaignBuilderWatchPath(result.id));
     // Serialize to only essential fields for context efficiency
     return {
         id: result.id,

package/dist/tools/context.d.ts

@@ -81,7 +81,7 @@ export declare function getCampaignContext(input: GetCampaignContextInput): Prom
         };
         watchUrl: {
             urlPresent: boolean;
-            signed: boolean;
+            direct: boolean | undefined;
             redirectPath: string | null;
         };
         table: {

package/dist/tools/context.js

@@ -178,7 +178,7 @@ export function markCampaignContextDirty(campaignId, reason) {
             },
             watchUrl: {
                 urlPresent: false,
-                signed: false,
+                direct: false,
                 redirectPath: null,
             },
             table: {

package/dist/tools/leads.d.ts

@@ -2460,6 +2460,11 @@ export declare function confirmLeadList(input: ConfirmLeadListInput): Promise<{
         rowIds?: string[];
         requestedTargetLeadCount?: number;
         sourceRowLimit?: number;
+        async?: boolean;
+        campaignTableReady?: boolean;
+        importStatus?: string | null;
+        remainingRowCount?: number | null;
+        rowCount?: number | null;
     };
     boundedReviewBatch: {
         requestedTargetLeadCount: number;

package/dist/tools/leads.js

@@ -2199,7 +2199,30 @@ export async function confirmLeadList(input) {
     if (!resolvedLeadListId) {
         throw new Error("confirm_lead_list requires sourceLeadListId");
     }
-    const effectiveCurrentStep = currentStep === undefined ? "confirm-lead-list" : currentStep;
+    const safePostConfirmCurrentSteps = new Set([
+        "filter-choice",
+        "create-icp-rubric",
+        "apply-icp-rubric",
+        "validate-sample",
+        "auto-execute-leads",
+        "messages",
+        "auto-execute-messaging",
+        "awaiting-user-greenlight",
+        "settings",
+        "sequence",
+        "send",
+        "claude-greenlight",
+        "running",
+    ]);
+    const effectiveCurrentStep = currentStep === undefined
+        ? "filter-choice"
+        : typeof currentStep === "string" &&
+            currentStep.length > 0 &&
+            safePostConfirmCurrentSteps.has(currentStep)
+            ? currentStep
+            : currentStep === null
+                ? null
+                : "filter-choice";
     const shouldSetCurrentStep = typeof effectiveCurrentStep === "string" && effectiveCurrentStep.length > 0;
     let readiness;
     const leadListMeta = await api.get(`/api/v3/workflow-tables/${resolvedLeadListId}?mode=meta`);
@@ -2257,13 +2280,27 @@ export async function confirmLeadList(input) {
         }
         throw new Error("Import still in progress. Keep the campaign at confirm-lead-list; retry readiness, cancel the import, or re-run-source before launching post-import scouts.");
     }
-    const importResult = await api.post(`/api/v3/campaign-builder/import-leads`, {
+    const isTerminalAccessError = (error) => error instanceof SellableApiError && [401, 403, 404].includes(error.status);
+    const formatTerminalAccessError = (error) => {
+        if (error.status === 401 || error.status === 403) {
+            return "Campaign or lead-list access failed. Fix workspace/auth access before retrying confirm_lead_list.";
+        }
+        return "Campaign or source lead list could not be found. Re-open the correct campaign or reselect the source list before retrying confirm_lead_list.";
+    };
+    const importResult = await api
+        .post(`/api/v3/campaign-builder/import-leads`, {
         sourceLeadListId: resolvedLeadListId,
         campaignOfferId,
         campaignName,
         keepInSync,
         ...(typeof targetLeadCount === "number" ? { targetLeadCount } : {}),
         ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
+    })
+        .catch((error) => {
+        if (isTerminalAccessError(error)) {
+            throw new Error(formatTerminalAccessError(error));
+        }
+        throw error;
     });
     const campaignTableId = importResult.workflowTableId ?? importResult.campaignTableId;
     const requestedTargetLeadCount = typeof targetLeadCount === "number" && Number.isFinite(targetLeadCount)
@@ -2275,6 +2312,29 @@ export async function confirmLeadList(input) {
     const overflowRowIds = campaignTableId && requestedTargetLeadCount !== null
         ? importedRowIds.slice(requestedTargetLeadCount)
         : [];
+    const importedRowCount = importedRowIds.length > 0
+        ? importedRowIds.length
+        : typeof importResult.rowCount === "number"
+            ? importResult.rowCount
+            : typeof importResult.leadsImported === "number"
+                ? importResult.leadsImported
+                : 0;
+    const remainingRowCount = typeof importResult.remainingRowCount === "number"
+        ? importResult.remainingRowCount
+        : 0;
+    const importStatus = String(importResult.importStatus ?? "").toLowerCase();
+    const campaignTableReady = importResult.campaignTableReady === true ||
+        (!importResult.async &&
+            importStatus !== "pending" &&
+            importStatus !== "partial" &&
+            remainingRowCount <= 0 &&
+            importedRowCount > 0);
+    if (!campaignTableReady) {
+        throw new Error("Campaign review rows are still importing. Stay on lead import until the bounded campaign table is ready, then retry confirm_lead_list or wait_for_campaign_table_ready.");
+    }
+    if (importedRowCount <= 0) {
+        throw new Error("No usable review rows were kept for the campaign table. Tighten or change the source before continuing.");
+    }
     if (campaignTableId && overflowRowIds.length > 0) {
         const deleteBatchSize = 25;
         for (let index = 0; index < overflowRowIds.length; index += deleteBatchSize) {
@@ -2310,7 +2370,10 @@ export async function confirmLeadList(input) {
                 trimmedOverflowRowCount: overflowRowIds.length,
             }
             : undefined,
-        message: "Lead list imported into campaign table. Next: move to filter-choice, then wait_for_campaign_table_ready, then sample with get_rows_minimal.",
+        message: requestedTargetLeadCount !== null &&
+            leadListRowCount > requestedTargetLeadCount
+            ? `I found ${leadListRowCount} source candidates and imported the first ${Math.min(importedRowCount, requestedTargetLeadCount)} into the campaign review table.`
+            : "Lead list imported into the campaign review table. Next: sample rows with get_rows_minimal or continue into filter work.",
     };
 }
 export function getProviderPrompt(input) {

package/dist/tools/navigation.d.ts

@@ -81,7 +81,7 @@ export declare function computeCampaignNavigationStateFromCampaign(campaign: Cam
     };
     watchUrl: {
         urlPresent: boolean;
-        signed: boolean;
+        direct: boolean | undefined;
         redirectPath: string | null;
     };
     table: {
@@ -125,7 +125,7 @@ export declare function getCampaignNavigationState(input: GetCampaignNavigationS
     };
     watchUrl: {
         urlPresent: boolean;
-        signed: boolean;
+        direct: boolean | undefined;
         redirectPath: string | null;
     };
     table: {

package/dist/tools/navigation.js

@@ -281,9 +281,9 @@ function mapHeadlessToUiStep(step) {
         return "signal-discovery";
     if (step === "filter-choice")
         return "filter-choice";
-    if (step === "create-icp-rubric")
-        return "filter-rules";
-    if (step === "apply-icp-rubric" || step === "validate-sample") {
+    if (step === "create-icp-rubric" ||
+        step === "apply-icp-rubric" ||
+        step === "validate-sample") {
         return "filter-leads";
     }
     if (step === "messages" ||
@@ -381,7 +381,7 @@ function describeVisibleStep(step) {
             };
     }
 }
-function parseSignedWatchUrl(watchUrl, campaignId) {
+function parseWatchUrl(watchUrl, campaignId) {
     if (!watchUrl) {
         return {
             urlPresent: false,
@@ -392,26 +392,39 @@ function parseSignedWatchUrl(watchUrl, campaignId) {
     }
     try {
         const url = new URL(watchUrl);
+        const directPath = `/campaign-builder/${campaignId}`;
+        const isDirectCampaignUrl = url.pathname === directPath &&
+            (url.searchParams.get("mode") === "claude" ||
+                url.searchParams.get("mode") === "codex" ||
+                url.searchParams.get("mode") === "watch");
+        if (isDirectCampaignUrl) {
+            return {
+                urlPresent: true,
+                direct: true,
+                redirectPath: `${url.pathname}?${url.searchParams.toString()}`.replace(/\?$/, ""),
+                warning: null,
+            };
+        }
         const redirect = url.searchParams.get("redirect");
         const decodedRedirect = redirect ? decodeURIComponent(redirect) : null;
-        const signed = url.pathname === "/auth/continue" &&
+        const isLegacySigned = url.pathname === "/auth/continue" &&
             Boolean(url.searchParams.get("token")) &&
-            decodedRedirect === `/campaign-builder/${campaignId}?mode=claude`;
+            decodedRedirect?.startsWith(`${directPath}?mode=`) === true;
         return {
             urlPresent: true,
-            signed,
+            direct: false,
             redirectPath: decodedRedirect,
-            warning: signed
-                ? null
-                : "Watch URL is not a signed /auth/continue watch link for /campaign-builder/{campaignId}?mode=claude.",
+            warning: isLegacySigned
+                ? "Watch URL still uses a tokenized /auth/continue handoff. Return the safe direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL instead."
+                : "Watch URL is not a safe direct /campaign-builder/{campaignId}?mode={claude|codex} watch link.",
         };
     }
     catch {
         return {
             urlPresent: true,
-            signed: false,
+            direct: false,
             redirectPath: null,
-            warning: "Watch URL is malformed; recover a fresh signed /auth/continue watch link before browser handoff.",
+            warning: "Watch URL is malformed; recover a fresh safe direct campaign-builder watch link before browser handoff.",
         };
     }
 }
@@ -554,7 +567,7 @@ export function computeCampaignNavigationStateFromCampaign(campaign, options) {
             checkpoint: "send",
         }
         : describeVisibleStep(orientationStep);
-    const watchUrlState = parseSignedWatchUrl(campaign.watchUrl, campaign.id);
+    const watchUrlState = parseWatchUrl(campaign.watchUrl, campaign.id);
     if (watchUrlState.warning) {
         warnings.push(watchUrlState.warning);
     }
@@ -579,7 +592,7 @@ export function computeCampaignNavigationStateFromCampaign(campaign, options) {
         },
         watchUrl: {
             urlPresent: watchUrlState.urlPresent,
-            signed: watchUrlState.signed,
+            direct: watchUrlState.direct,
             redirectPath: watchUrlState.redirectPath,
         },
         table: {

package/dist/tools/readiness.d.ts

@@ -134,7 +134,7 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         };
         watchUrl: {
             urlPresent: boolean;
-            signed: boolean;
+            direct: boolean | undefined;
             redirectPath: string | null;
         };
         table: {
@@ -183,7 +183,7 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         };
         watchUrl: {
             urlPresent: boolean;
-            signed: boolean;
+            direct: boolean | undefined;
             redirectPath: string | null;
         };
         table: {
@@ -234,7 +234,7 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         };
         watchUrl: {
             urlPresent: boolean;
-            signed: boolean;
+            direct: boolean | undefined;
             redirectPath: string | null;
         };
         table: {

package/dist/tools/watch-url-security.js

@@ -1,7 +1,22 @@
 function sanitizeWatchUrlValue(value) {
-    // Watch URLs are intentional auth continuation handoffs for fresh browsers.
-    // Do not strip them here; redaction belongs in logs, not MCP tool results.
-    return value;
+    try {
+        const url = new URL(value);
+        if (url.pathname === "/auth/continue") {
+            const redirect = url.searchParams.get("redirect");
+            if (redirect) {
+                const direct = new URL(decodeURIComponent(redirect), url.origin);
+                const workspaceId = url.searchParams.get("workspaceId");
+                if (workspaceId && !direct.searchParams.has("workspaceId")) {
+                    direct.searchParams.set("workspaceId", workspaceId);
+                }
+                return direct.toString();
+            }
+        }
+        return value;
+    }
+    catch {
+        return value;
+    }
 }
 export function sanitizeWatchUrlsForMcpResult(value) {
     if (!value || typeof value !== "object")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.110",
+  "version": "0.1.112",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-campaign/SKILL.md

@@ -162,11 +162,11 @@ copy.
 ## Codex Watch Browser Handoff
 
 When a campaign tool returns `watchUrl`, treat it as an active browser handoff,
-not only a URL to print. A valid handoff link must be a signed
-`/auth/continue?token=...&redirect=/campaign-builder/{campaignId}?mode=claude`
-URL. `create_campaign.watchUrl`, `create_campaign({ campaignId }).watchUrl`,
-and `get_campaign.watchUrl` are all acceptable only when they return that signed
-shape.
+not only a URL to print. A valid handoff link must be a safe direct
+`/campaign-builder/{campaignId}?mode=claude` URL. `create_campaign.watchUrl`,
+`create_campaign({ campaignId }).watchUrl`, and `get_campaign.watchUrl` are all
+acceptable only when they return that direct campaign-builder shape, with
+`workspaceId` used only as a safe routing hint when needed.
 
 In Codex Desktop, when in-app browser control is available, open the returned watch link on the user's behalf. After opening it, inspect the browser-visible campaign state, then explain what the user is seeing before continuing with more campaign tools. Use customer language such as:
 
@@ -175,8 +175,8 @@ I’ll open the campaign view and keep it in sync as I build.
 ```
 
 If browser control is unavailable, provide the watch link without discussing the
-runtime limitation. In off-desktop Codex runs, make the signed link easy to
-copy/open, then continue with explicit customer-facing campaign progress and
+runtime limitation. In off-desktop Codex runs, make the direct watch link easy
+to copy/open, then continue with explicit customer-facing campaign progress and
 `get_campaign_navigation_state` orientation checks.
 Use this fallback shape:
 
@@ -188,9 +188,9 @@ here as I build.
 ```
 
 If opening the watch link lands on an auth, 404, permission, blank, or visible
-error state, report only what is visible, recover a fresh signed watch link once
-with `create_campaign({ campaignId })` or `get_campaign`, and try that link. Do
-not claim the browser was opened, inspected, or synchronized unless the visible
+error state, report only what is visible, recover a fresh watch link once with
+`create_campaign({ campaignId })` or `get_campaign`, and try that link. Do not
+claim the browser was opened, inspected, or synchronized unless the visible
 browser state was actually observed. Do not claim the browser was opened unless
 it was opened and observed.
 

package/skills/create-campaign-v2/SKILL.md

@@ -165,7 +165,7 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   ask in chat only when the run is explicitly a non-interactive smoke/rehearsal.
 
 - Customer-facing progress updates must use product language. Say "quick
-  setup choices", "campaign brief", "lead sourcing", and "approval" instead of
+  setup choices", "campaign brief", "Find Leads", and "approval" instead of
   `request_user_input`, Default mode, MCP namespaces, plugin caches, prompt
   loading, runbooks, local skill files, skill versions, npm/package details,
   repo-local files, VPS/off-desktop/browser automation limitations, or
@@ -181,6 +181,13 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   or safe launch. Do not say "persist", "local draft folder", "artifact",
   "mkdir", "campaign thesis", or "same approved campaign thesis" in
   customer-facing progress copy.
+- Watch guide copy must use the single `watchNarration` object whenever you set
+  `currentStep` or report visible progress in a watched run. Read
+  `references/watch-guide-narration.md` for the compact screen contract. Do not
+  send separate guide headline/body args. In Find Leads, the static stage label
+  is not enough: name the active lane/provider, what search or sample you are
+  trying, and why it fits this campaign. Do not promise time estimates in guide
+  copy.
 - Every approval gate must include live campaign access after the readable inline
   content. Show a short `Watch link:` line with the campaign link when a
   campaign shell exists. In normal customer runs, do not show `Open artifact:`
@@ -401,7 +408,7 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   `RevOps`, `outbound systems`, or `pipeline architecture` unless they are
   translated into what the user can understand.
 
-  After rendering that brief, ask for brief approval before lead sourcing in
+  After rendering that brief, ask for brief approval before Find Leads in
   hosted net-new runs. The user-facing choice should be approve/revise language,
   not "looks good".
   Approval options should refer to what the user just read, e.g. `Approve this
@@ -422,16 +429,15 @@ brief`, `Revise target`, `Revise offer/proof`, and `Other / custom`.
 
   The approval question can be based on the rendered brief in chat and the live
   campaign brief. Do not wait for file-write chrome before asking for approval.
-  Before lead sourcing, call `update_campaign({ campaignId, campaignBrief,
-  currentStep: "pick-provider" })` after approval so the watch link moves out of
-  Plan while the main thread compares source paths.
+  Before Find Leads, call `update_campaign({ campaignId, campaignBrief,
+  currentStep: "pick-provider", watchNarration: { ... } })` after approval so
+  the watch link moves out of Plan while the main thread compares source paths.
 
 - After the brief is approved, show the next progress line:
   `Cool. Now I'm going to find people who are both a good fit and active enough
 to be worth a LinkedIn test. I'll compare source paths by expected volume,
 sampled ICP fit, activity/warmth signal, cleanup risk, and tradeoffs. This
-usually takes ~3-5 min, and I'll show you the source decision + sample before
-anything goes live.`
+will end with a source decision + sample before anything goes live.`
 - In watch mode, do not leave the user sitting on only `pick-provider` while
   source scouts run. Move the campaign to the likely primary source lane
   (`signal-discovery`, `sales-nav`, or `prospeo`) before background source
@@ -447,9 +453,8 @@ message we should test.`
 - During long post-intake work, show concise progress checkpoints before the
   next expensive stage: source being checked, source switch/tradeoff if any,
   lead sample usable, filter/message drafting, and message-review rule loading.
-  Each checkpoint should include a rough remaining time when useful. If a step
-  exceeds its estimate by roughly a minute or more, acknowledge it lightly once
-  and explain why the extra care helps the campaign. Example:
+  Each checkpoint should say what changed, what is being checked next, and why
+  that matters for the campaign. Do not invent remaining-time estimates. Example:
 
   ```text
   This is taking a little longer than I expected, sorry. I’m being careful here
@@ -623,7 +628,7 @@ workstreams`, `in parallel`, or `background` unless parallel branches were
 There are four customer-visible gates in the net-new hosted flow:
 
 - `brief-review` asks whether to approve the rendered campaign brief before
-  lead sourcing starts. Do not skip this by inferring approval from setup
+  Find Leads starts. Do not skip this by inferring approval from setup
   answers.
 - `lead-review` / source decision asks whether to approve the selected source
   path and sample before moving into filter/message work. Do not skip this by

package/skills/create-campaign-v2/core/flow.v2.json

@@ -1,12 +1,12 @@
 {
   "version": "v2",
   "workflow": "create-campaign-v2",
-  "principle": "CampaignOffer state and the watch link are canonical from the first brief onward. Disk artifacts are optional debug/UAT diagnostics, not the normal customer surface. Resume, gating, and handoff read campaign state first. Start from user intake, create a watchable campaign shell with a v1 brief, update currentStep before major visible work, attach source/search state to that CampaignOffer, import the bounded review batch before post-import fit/message scouts, save rubrics and an approved message template, then queue the 15-row cascade and hand off to settings/sequence/start.",
+  "principle": "CampaignOffer state and the watch link are canonical from the first brief onward. Disk artifacts are optional debug/UAT diagnostics, not the normal customer surface. Resume, gating, and handoff read campaign state first. Start from user intake, create a watchable campaign shell with a v1 brief, update currentStep and watchNarration before major visible work, attach source/search state to that CampaignOffer, import the bounded review batch before post-import fit/message scouts, save rubrics and an approved message template, then queue the 15-row cascade and hand off to settings/sequence/start.",
   "artifactPolicy": {
     "normalCustomerPath": "Use CampaignOffer state, MCP responses, provider search state, and campaign table rows. Do not create, read, link, or surface local draft files unless debug/UAT mode is explicit or the user asks for them.",
     "debugArtifactsAreOptional": true,
     "requiredArtifactsApplyWhen": "legacy resume, fixture validation, or explicit debug/UAT mode only",
-    "customerFacingAccess": "Watch link and live campaign currentStep"
+    "customerFacingAccess": "Watch link, live campaign currentStep, and concise watchNarration"
   },
   "commitGateChoices": [
     "approve",
@@ -225,9 +225,6 @@
             "watch the draft campaign as it fills in",
             "no leads import and nothing sends yet"
           ],
-          "timeEstimates": {
-            "campaignBrief": "~1-2 min"
-          },
           "forbiddenWording": [
             "brief.md",
             "lead-review.md",
@@ -279,10 +276,12 @@
             "name",
             "campaignBrief",
             "clientProspectId or senderLinkedinUrl",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "create-offer"
+            "currentStep": "create-offer",
+            "watchNarration.stage": "brief-review"
           },
           "briefMode": "v1 campaign brief shown to the user; not an empty placeholder",
           "capture": [
@@ -306,7 +305,8 @@
             "campaignId",
             "watchUrl",
             "campaignBrief",
-            "currentStep:create-offer"
+            "currentStep:create-offer",
+            "watchNarration: brief-review with approve-the-brief guidance"
           ]
         },
         {
@@ -330,7 +330,7 @@
             "campaignBrief"
           ],
           "watchUrlSource": "create_campaign.watchUrl",
-          "requiredWatchUrlShape": "signed /auth/continue?token=...&redirect=/campaign-builder/{campaignId}?mode=claude",
+          "requiredWatchUrlShape": "direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL",
           "codexBrowserHandoff": {
             "openWhenAvailable": true,
             "inspectBeforeContinuing": true,
@@ -444,7 +444,7 @@
           ],
           "debugOrUatOnly": true,
           "requiredBeforeTransition": false,
-          "reconcileRule": "If debug/UAT artifacts are enabled, verify the sidecar persisted the same brief shown in chat. Normal customer lead sourcing reads CampaignOffer.campaignBrief, not brief.md.",
+          "reconcileRule": "If debug/UAT artifacts are enabled, verify the sidecar persisted the same brief shown in chat. Normal customer Find Leads work reads CampaignOffer.campaignBrief, not brief.md.",
           "chatRenderRule": "Do not block the brief approval question or find-leads transition on this step. Only mention artifact persistence if debug/UAT mode fails or the user asks."
         },
         {
@@ -457,7 +457,8 @@
           "when": "after_user_brief_confirmed_or_auto_continue",
           "fields": [
             "campaignBrief",
-            "currentStep:pick-provider"
+            "currentStep:pick-provider",
+            "watchNarration: find-leads with the first provider/lane being tested"
           ],
           "fallback": "If campaignId is missing from CampaignOffer state, stop; shell-first flow requires an existing campaign before sourcing leads.",
           "readsCampaignStateFirst": true,
@@ -512,20 +513,23 @@
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "pick-provider"
+            "currentStep": "pick-provider",
+            "watchNarration.stage": "find-leads"
           },
           "when": "before_source_scouts_or_provider_search",
-          "chatRenderRule": "Move the campaign watch view to Find Contacts before the main thread starts comparing source paths. Do not mention MCP or local artifacts."
+          "chatRenderRule": "Move the campaign watch view to Find Leads before the main thread starts comparing source paths. The watchNarration headline/body must name the likely provider or lane being tested and why it fits this campaign. Do not mention MCP or local artifacts."
         },
         {
           "action": "advance_watch_to_initial_source_lane",
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "currentStepByPrimaryLane": {
             "signals": "signal-discovery",
@@ -536,7 +540,7 @@
             "uploadedDomains": "prospeo"
           },
           "when": "before_background_source_scouts",
-          "rule": "Choose the likely primary visible source lane from source intake, brief preference, or the best first lane the main thread will actually search. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
+          "rule": "Choose the likely primary visible source lane from source intake, brief preference, or the best first lane the main thread will actually search. Send watchNarration with stage find-leads that says what search was tried or is being tried next, what sample is being checked, and why it helps this campaign. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
         },
         {
           "action": "run_first_campaign_attached_source_search",
@@ -565,7 +569,7 @@
             "source decision + sample",
             "no import or enrichment yet"
           ],
-          "timeEstimate": "~3-5 min"
+          "watchNarrationRule": "Do not include time estimates. Use current, campaign-specific search reasoning instead."
         },
         {
           "action": "read_optional_source_intake",
@@ -755,7 +759,7 @@
             "import the first 15-row review batch before fit/message work",
             "selectedLeadListId stays the source list and workflowTableId is the campaign table"
           ],
-          "timeEstimate": "~2-3 min",
+          "watchNarrationRule": "Do not include time estimates. Say what review-batch work is happening and what the user will approve next.",
           "chatRenderRule": "Lead source is set. Next import and confirm only the first 15-row review batch into the campaign table. After workflowTableId exists, run the fit-filter and message-generation workstreams from the campaign table sample. If real parallel MCP/tool branches or host subagents were actually launched, say so; otherwise say the branches will run sequentially. Never claim parallelism unless parallel execution actually started."
         },
         {
@@ -929,10 +933,12 @@
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "filter-choice"
+            "currentStep": "filter-choice",
+            "watchNarration.stage": "fit-message"
           }
         }
       ],
@@ -1489,7 +1495,8 @@
             "message-review-decision.md"
           ],
           "requiredValues": {
-            "currentStep": "validate-sample"
+            "currentStep": "validate-sample",
+            "watchNarration.stage": "review-ready"
           },
           "when": "after_update_campaign_brief_succeeds",
           "requiredBeforeCascade": true,
@@ -1846,7 +1853,7 @@
             "Campaign created",
             "approved brief",
             "Open this to watch",
-            "lead sourcing",
+            "Find Leads",
             "rubric scoring",
             "messaging populate live",
             "Watch link:"
@@ -2118,10 +2125,12 @@
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "awaiting-user-greenlight"
+            "currentStep": "awaiting-user-greenlight",
+            "watchNarration.stage": "review-ready"
           }
         }
       ],
@@ -2188,7 +2197,7 @@
         },
         {
           "action": "surface_sender_and_slack_handoff",
-          "settingsUrlPattern": "/campaign-builder/{campaignId}/settings?mode=claude",
+          "settingsUrlPattern": "/campaign-builder/{campaignId}/settings?mode={claude|codex}",
           "requiredVisibleContent": [
             "connect or select a LinkedIn sender",
             "Slack reply review",

package/skills/create-campaign-v2/references/watch-guide-narration.md

@@ -0,0 +1,141 @@
+# Watch Guide Narration
+
+Use one `watchNarration` object whenever you set `currentStep` or report visible
+progress in a watched create-campaign run. Do not add separate guide headline or
+body args.
+
+## Render
+
+```text
+Building campaign with {Claude Code or Codex}               [Exit watch mode]
+[progress bar]  {stage label} · Step {n} of 5
+
+{headline}
+{visibleState} {agentIntent}
+
+Next: {nextAction}
+{safety?}
+```
+
+UI owns the header, driver label, button, progress bar, step count, and static
+stage labels. The driver label comes from the watch URL mode (`mode=claude` or
+`mode=codex`), so do not add separate guide args for it. You own `stage`,
+`headline`, `visibleState`, `agentIntent`, and any exceptional `nextAction`,
+`safety`, `workerStatuses`, or `blockedReason`.
+
+## Copy Rules
+
+- One primary user action per frame.
+- Headline under 8 words.
+- Body is 1-2 short sentences total.
+- Say where the user acts: usually `in Claude Code`, `in Codex`, or `in chat`,
+  matching the host that created the watch URL.
+- `Find Leads` is only the static progress label. The copy must name the active
+  lane/provider and campaign strategy: Signal Discovery, Sales Nav, Prospeo,
+  Apollo, or existing list.
+- During search iteration, say what you tried, what you are trying next, what
+  sample you are checking, and why that helps this campaign.
+- Avoid internal terms: MCP, tool, currentStep, workflow table, scout, debug.
+- Do not invent time estimates.
+
+## Stages
+
+| stage          | UI label      | Next          |
+| -------------- | ------------- | ------------- |
+| `brief-review` | Brief review  | Find Leads    |
+| `find-leads`   | Find Leads    | Review batch  |
+| `review-batch` | Review batch  | Fit + message |
+| `fit-message`  | Fit + message | Review ready  |
+| `review-ready` | Review ready  | Validation    |
+
+## Examples
+
+Brief review:
+
+```json
+{
+  "stage": "brief-review",
+  "headline": "Approve the brief in Codex",
+  "visibleState": "This page is a live preview of the campaign brief.",
+  "agentIntent": "Ask for changes in chat if anything looks off.",
+  "nextAction": "Find Leads"
+}
+```
+
+Signal Discovery:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Testing Signal Discovery",
+  "visibleState": "You are watching Signal Discovery search posts about Claude Code and GTM automation.",
+  "agentIntent": "Codex is sampling engagers to see if they match the founder/operator campaign brief.",
+  "nextAction": "Review batch"
+}
+```
+
+Search iteration:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Tightening the search",
+  "visibleState": "The first Signal Discovery search was broad, so Codex is trying a narrower Claude Code founder lane.",
+  "agentIntent": "It is sampling a few engagers before importing so the review batch stays on-brief.",
+  "nextAction": "Review batch"
+}
+```
+
+Review batch:
+
+```json
+{
+  "stage": "review-batch",
+  "headline": "Preparing your review batch",
+  "visibleState": "This page shows the leads Codex selected for review.",
+  "agentIntent": "Codex is preparing the first campaign batch from those leads.",
+  "nextAction": "Fit + message"
+}
+```
+
+Fit + message:
+
+```json
+{
+  "stage": "fit-message",
+  "headline": "Building fit and message",
+  "visibleState": "Codex is preparing the campaign's fit rules and first message sample.",
+  "agentIntent": "It is checking who should receive this campaign and what the first offer should say.",
+  "nextAction": "Review ready",
+  "workerStatuses": {
+    "leadFitBuilder": "running",
+    "messageDraftBuilder": "running"
+  }
+}
+```
+
+Review ready:
+
+```json
+{
+  "stage": "review-ready",
+  "headline": "Review fit and message",
+  "visibleState": "The fit rules and message sample are ready.",
+  "agentIntent": "Approve them or ask for changes in chat.",
+  "nextAction": "Validation",
+  "safety": "Codex will only continue after you approve."
+}
+```
+
+Blocked/recovering:
+
+```json
+{
+  "stage": "review-batch",
+  "headline": "Fixing the review batch",
+  "visibleState": "The browser is not showing the campaign batch yet.",
+  "agentIntent": "Codex is reconnecting the campaign state before moving forward.",
+  "nextAction": "Fit + message",
+  "blockedReason": "Campaign batch is not ready yet."
+}
+```

package/skills/create-campaign-v2/references/watch-link-handoff.md

@@ -11,12 +11,12 @@ gating, and handoff read campaign state first.
 
 ## Plumbing Reuse
 
-`create_campaign` already returns a signed `/auth/continue` `watchUrl` on the response
-(`CampaignDetail.watchUrl` in `mcp/sellable/src/tools/campaigns.ts`). V2 does
-NOT mint a new token, does NOT call a different route, and does NOT construct
-the URL locally. Capture whatever `watchUrl` the existing tool returns and
-surface it verbatim. The link must be able to authenticate a fresh browser and
-land on the campaign builder without sending the user to signup.
+`create_campaign` already returns a safe direct campaign-builder `watchUrl` on
+the response (`CampaignDetail.watchUrl` in
+`mcp/sellable/src/tools/campaigns.ts`). V2 does NOT mint a new token, does NOT call
+a different route, and does NOT construct the URL locally. Capture whatever
+`watchUrl` the existing tool returns and surface it verbatim. The link must
+land on the campaign builder without exposing token secrets in the MCP result.
 
 ## Shell-First Link
 
@@ -45,7 +45,7 @@ Cool, let's find leads.
 Atomic-mint legacy orientation:
 
 ```text
-Open this to watch lead sourcing, rubric scoring, and messaging populate live.
+Open this to watch Find Leads, rubric scoring, and messaging populate live.
 ```
 
 The exact wording may be adapted for tone, but the copy must make three things
@@ -59,7 +59,7 @@ If shell creation fails or the response is missing `watchUrl`, stop and surface
 the error. Do not continue into campaignless source scouting in the active
 shell-first flow.
 If a legacy atomic-mint response is missing `watchUrl`, it is not a silent skip.
-Stop before `save_rubrics` and recover the missing signed URL first.
+Stop before `save_rubrics` and recover the missing watch URL first.
 
 ## Step Orientation
 
@@ -81,19 +81,19 @@ Do not spam the link between internal tool calls.
 On resume:
 
 1. Load the `CampaignOffer` for the campaign being resumed.
-2. Recover the signed auth continuation link through the existing resume path
+2. Recover the direct watch link through the existing resume path
    (`create_campaign({ campaignId })` when available).
 3. Inspect `currentStep` and print a short orientation for where the user will
    land now.
 4. Print the recovered `watchUrl`.
 
-The re-surface must use the signed `watchUrl` from the tool response, not a
+The re-surface must use the `watchUrl` from the tool response, not a
 cached or reconstructed URL.
 
 ## Hard Rules
 
 - Never fabricate or reconstruct the URL locally.
-- The watch link must authenticate a fresh browser via `/auth/continue`.
+- The watch link must be a safe direct campaign-builder URL.
 - Missing `watchUrl` is an error, not a silent skip.
 - The first watch link must be shown only after the v1 brief is on the campaign.
 - A watch link is not approval to import, attach sequence, or start.