@mj-biz-apps/marketing-server 0.0.0 → 0.2.0

package/dist/agents/MarketingStrategyOnboardingAgent.js

@@ -0,0 +1,1264 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass, UUIDsEqual } from "@memberjunction/global";
+import { createHash } from "node:crypto";
+import { BaseAgent } from "@memberjunction/ai-agents";
+import { LogError, LogStatus, RunView } from "@memberjunction/core";
+import { BaseMarketingAgent } from './BaseMarketingAgent.js';
+import { getGuidance, decideOnboardingStep, MESSAGING_SECTION_KEY, renderSpecMarkdown, isFoundationKey, PLAN_KEYS } from '@mj-biz-apps/marketing-core';
+// These are marketing-core services (they moved out of the Actions package on 2026-08-08 to
+// sit where every other open app keeps services). Imported from their defining package rather
+// than re-exported through Actions — see typescript-style.md, no cross-package re-exports.
+import { getOnboardingSnapshot, synthesizeFoundations, synthesizeSection, createStrategyApprovalRequest, synthesizePlan, materializeStrategyVersion, recordStrategyApprovalDecision, writeFinalizeRecommendations, } from '@mj-biz-apps/marketing-core';
+/**
+ * Marketing Strategy Onboarding Agent — driver class.
+ *
+ * Owns the onboarding SHELL (action-surface rework Phase 2): the deterministic
+ * grill state machine runs in code before every prompt turn, not as an
+ * LLM-invoked action. Each turn this driver:
+ *
+ *   1. Loads the DB snapshot (strategy header → current version → Foundation
+ *      confidences) and the conversation-threaded counters from the payload.
+ *   2. Asks `decideOnboardingStep` (pure, marketing-core) what happens next.
+ *   3. If the machine says synthesize AND the payload carries gathered
+ *      evidence (`payload.rawSources`), it runs the synthesis service RIGHT
+ *      HERE — LLM extraction + StrategySection persistence — then re-consults
+ *      the machine, clears the consumed raw evidence (Rev 5 phase rule:
+ *      nothing downstream may read raw source text), and records a
+ *      `payload.lastSynthesis` summary for the prompt to narrate.
+ *   4. Publishes the resulting STATE as `payload.onboarding` (phase, weak vs
+ *      settled sections, what has been synthesized, approval status). The
+ *      template branches on that state; it is never handed a command.
+ *
+ * That last point is the Skip pattern and it is load-bearing. Skip's agents
+ * branch their prompts on payload the model can see and verify
+ * (`{% if _CURRENT_PAYLOAD.changeRequest %}`), and only ever inject evidence
+ * into preparePromptParams. An injected imperative is a second control channel
+ * with no defined behavior when it is missing — the hole two runaway-loop
+ * incidents fell through. State always has a branch.
+ *
+ * The LLM keeps exactly what it is good at: choosing evidence tools, asking
+ * sharp questions, and narrating. Flow control is code.
+ *
+ * The former `Check Onboarding Progress`, `Synthesize Foundations`, and
+ * `Synthesize Strategy Section` actions are retired; their engines live in
+ * `@mj-biz-apps/marketing-core` strategyOnboardingService.
+ *
+ * Brand context comes from BaseMarketingAgent's ladder (brand is the unit of
+ * marketing scope and of authorization); the onboarding-questions guidance is
+ * injected at start.
+ *
+ * Admin-only (onboarding governance — strategy artifacts are Leadership-Set).
+ */
+/**
+ * Hard cap on shell passes within one run. Skip's drivers bound their loops with
+ * a literal MAX_* constant and a break rather than trusting the model
+ * (unified-code-generator's MAX_FIX_ITERATIONS, query-design's attemptsAllowed).
+ * A conversational turn needs 2-3 passes; more means the state stopped moving.
+ */
+const MAX_SHELL_PASSES_PER_RUN = 6;
+/**
+ * How many of the newest conversation details to scan when resolving the
+ * artifact version the founder approved. Artifacts are linked per-detail and
+ * we only ever want the newest one, so a bounded newest-first window is both
+ * correct and keeps the generated `IN (...)` filter from growing with the
+ * length of the conversation.
+ */
+const RECENT_DETAILS_SCANNED_FOR_ARTIFACT = 200;
+const PHASE_BY_ACTION = {
+    'synthesize-foundations': 'Gather',
+    'grill': 'Grill',
+    'synthesize-strategy-section': 'Grill',
+    'finalize-strategy-onboarding': 'ReadyForApproval',
+    'complete': 'Complete',
+};
+let MarketingStrategyOnboardingAgent = class MarketingStrategyOnboardingAgent extends BaseMarketingAgent {
+    async initializeStartingPayload(params) {
+        await super.initializeStartingPayload(params);
+        const payload = params.payload;
+        if (!payload)
+            return;
+        if (!payload.guidanceOnboardingQuestions) {
+            payload.guidanceOnboardingQuestions = await getGuidance('onboarding-questions', params.contextUser);
+        }
+        // Defense in depth: the framework's absolute iteration ceiling is 5000,
+        // which is runaway territory for a conversational onboarding turn.
+        // Belt to the agent record's MaxIterationsPerRun (the knob Skip sizes
+        // per agent, 3-25). This is the absolute net, kept low for a chat turn.
+        params.absoluteMaxIterations = Math.min(params.absoluteMaxIterations ?? 12, 12);
+    }
+    async preparePromptParams(config, payload, params) {
+        // Shell runs BEFORE the base copies payload → prompt data, so this
+        // turn's state and synthesis results reach the template render.
+        await this.runOnboardingShell(payload, params);
+        return super.preparePromptParams(config, payload, params);
+    }
+    /**
+     * Deterministic brand resolution for multi-brand users. The base ladder
+     * sets `authorizedBrands` (instead of `brandId`) when the user is
+     * authorized for several brands, and the prompt can't be trusted to write
+     * `brandId` back — so when the founder has NAMED one of those brands
+     * anywhere in the conversation, the shell resolves it itself.
+     * Longest-name match wins ("Acme Health" beats "Acme").
+     *
+     * Brand names are only unique WITHIN a company, so a tie between two
+     * equally-long matched names is broken by the parent company name also
+     * appearing in the conversation. Still ambiguous ⇒ resolve nothing and
+     * let the agent ask; guessing here would write a strategy onto the wrong
+     * tenant's brand.
+     */
+    /** Is this brand one the caller actually holds a grant for? */
+    isAuthorizedBrand(payload, brandId) {
+        const brands = Array.isArray(payload.authorizedBrands) ? payload.authorizedBrands : [];
+        return brands.some(b => !!b && typeof b === 'object'
+            && typeof b.brandId === 'string'
+            && UUIDsEqual(b.brandId, brandId));
+    }
+    resolveBrandFromConversation(payload, params) {
+        const brands = (Array.isArray(payload.authorizedBrands) ? payload.authorizedBrands : [])
+            .filter((b) => !!b && typeof b === 'object');
+        if (brands.length === 0)
+            return undefined;
+        const rawText = (params.conversationMessages ?? [])
+            .filter(m => m.role === 'user')
+            .map(m => typeof m.content === 'string' ? m.content : m.content.map(b => b.type === 'text' ? b.content : '').join(' '))
+            .join('\n');
+        if (!rawText)
+            return undefined;
+        const text = rawText.toLowerCase();
+        // The AwaitingBrand form is a buttongroup whose option VALUES are brand
+        // ids, so a founder who clicks a button sends the UUID, not the name.
+        // Observed live: answering "Skip" via the button produced
+        // "Which brand are we onboarding?: B1CBC003-…" and name-matching found
+        // nothing, so the shell stayed in AwaitingBrand while the model went
+        // ahead and claimed the brand on its own. Match the id FIRST — it is
+        // exact and unambiguous — then fall back to the name.
+        // Pull out any UUID-shaped tokens and compare them properly. Extract-
+        // then-compare rather than substring-matching a lowercased blob: MJ's
+        // UUIDsEqual is the sanctioned comparison (SQL Server returns
+        // uppercase, Postgres lowercase, so `===` silently fails across
+        // platforms — see guides/UUID_COMPARISON_GUIDE.md).
+        const uuidsInText = rawText.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi) ?? [];
+        for (const token of uuidsInText) {
+            const hit = brands.find(b => typeof b.brandId === 'string' && UUIDsEqual(b.brandId, token));
+            if (hit)
+                return hit.brandId;
+        }
+        const matches = [];
+        for (const b of brands) {
+            const name = typeof b.name === 'string' ? b.name.trim().toLowerCase() : '';
+            const id = typeof b.brandId === 'string' ? b.brandId : undefined;
+            if (!id || name.length < 3)
+                continue;
+            if (text.includes(name)) {
+                matches.push({ id, len: name.length, companyName: typeof b.companyName === 'string' ? b.companyName.trim().toLowerCase() : '' });
+            }
+        }
+        if (matches.length === 0)
+            return undefined;
+        const longest = Math.max(...matches.map(m => m.len));
+        const top = matches.filter(m => m.len === longest);
+        if (top.length === 1)
+            return top[0].id;
+        const byCompany = top.filter(m => m.companyName.length >= 3 && text.includes(m.companyName));
+        return byCompany.length === 1 ? byCompany[0].id : undefined;
+    }
+    /**
+     * The founder's own words ARE the interview evidence. Reading them here
+     * (rather than asking the model to copy them into the payload and yield)
+     * removes the round-trip that made the loop possible: by the time the
+     * prompt runs, synthesis has already happened and the model's only job is
+     * to talk to the founder.
+     *
+     * Turns already folded into the running objective are skipped, so a
+     * re-render of the same turn can't double-count them.
+     */
+    deriveInterviewEvidence(payload, params) {
+        const consumed = asStringArray(payload.consumedUserTurns);
+        const out = [];
+        const messages = (params.conversationMessages ?? []).filter(m => m.role === 'user');
+        messages.forEach((m) => {
+            const text = typeof m.content === 'string'
+                ? m.content
+                : m.content.map(b => b.type === 'text' ? b.content : '').join(' ');
+            const body = text.trim();
+            if (body.length < 20)
+                return; // "yes" / "idk" carry no evidence
+            // P7: content-addressed, so a shifted message window can't cause a
+            // re-ingest (double-counted evidence) or a skip (lost answer).
+            const key = `turn-${createHash('sha1').update(body).digest('hex').slice(0, 12)}`;
+            if (consumed.includes(key))
+                return;
+            out.push({ channel: 'interview', label: 'Founder input', locator: key, text: body });
+        });
+        // NOTE: deliberately does NOT mark these consumed. The shell commits
+        // them only after a synthesis actually ingests them (commitConsumedTurns),
+        // because marking here discarded the founder's answers on any turn where
+        // the state machine chose to grill instead of synthesize.
+        return out;
+    }
+    /**
+     * Enforce the interview contract in CODE, not in the prompt.
+     *
+     * Skip's drivers validate the model's proposed next step and correct it
+     * (SkipRequirementsExpertAgent.validateChatNextStep demotes Chat->Success in
+     * update mode). A prompt rule is advice the model may ignore; this is the
+     * layer where an invariant actually holds.
+     *
+     * Two invariants:
+     *  - In Grill, a reply MUST carry the batched questions. Observed live: the
+     *    model narrated the synthesis and said "I'll start with Customer
+     *    Journey" with no form attached, burning the founder's turn.
+     *  - In AwaitingBrand, a reply MUST offer the brand choices, or the founder
+     *    is asked a question with no way to answer it that the shell can read.
+     *
+     * A corrective Retry carries an errorMessage, so it counts against the
+     * framework's consecutive-unproductive-retry cap (10) and cannot loop.
+     */
+    /**
+     * P2 — terminate on Complete.
+     *
+     * `Chat` always terminates the TURN, but the run only *succeeds* on a
+     * Success step, and `FinalPayloadValidation` is evaluated nowhere else. An
+     * interview that can never emit Success can never be validated and never
+     * signals completion to a caller.
+     */
+    async validateChatNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
+        const payload = currentPayload;
+        const state = payload?.onboarding;
+        const phase = typeof state?.phase === 'string' ? state.phase : null;
+        if (phase === 'Complete') {
+            LogStatus('OnboardingShell: interview complete — ending the run with Success');
+            return { ...nextStep, step: 'Success', terminate: true };
+        }
+        return this.enforceInterviewContract(params, nextStep, currentPayload, agentRun, currentStep, phase, state);
+    }
+    /** Grill/AwaitingBrand replies must carry the form that makes them answerable. */
+    async enforceInterviewContract(params, nextStep, currentPayload, agentRun, currentStep, phase, state) {
+        const hasForm = !!nextStep.responseForm;
+        if (!hasForm && phase === 'Grill') {
+            const weak = Array.isArray(state?.weakSections) ? state.weakSections.length : 0;
+            if (weak > 0) {
+                LogStatus('OnboardingShell: rejecting a Grill reply with no responseForm — asking the model to attach the questions');
+                return {
+                    ...nextStep,
+                    step: 'Retry',
+                    terminate: false,
+                    errorMessage: `You are in the Grill phase with ${weak} Weak section(s) but attached no responseForm. ` +
+                        `Do not announce that you will ask questions — ask them now: one sharp question per Weak ` +
+                        `section (max five), every field optional, each with a placeholder, in a single responseForm ` +
+                        `alongside your message.`,
+                    retryInstructions: `You are in the Grill phase with ${weak} Weak section(s) but attached no responseForm. ` +
+                        `Do not announce that you will ask questions — ask them now: one sharp question per Weak ` +
+                        `section (max five), every field optional, each with a placeholder, in a single responseForm ` +
+                        `alongside your message.`,
+                };
+            }
+        }
+        if (!hasForm && phase === 'AwaitingBrand') {
+            const choices = Array.isArray(state?.brandChoices)
+                ? state.brandChoices.length : 0;
+            if (choices > 1) {
+                LogStatus('OnboardingShell: rejecting an AwaitingBrand reply with no brand buttons');
+                return {
+                    ...nextStep,
+                    step: 'Retry',
+                    terminate: false,
+                    errorMessage: 'You asked which brand without attaching a responseForm. Offer the authorized brands as a ' +
+                        'buttongroup whose option values are the brand ids, so the answer can be read deterministically.',
+                    retryInstructions: 'You asked which brand without attaching a responseForm. Offer the authorized brands as a ' +
+                        'buttongroup whose option values are the brand ids, so the answer can be read deterministically.',
+                };
+            }
+        }
+        return super.validateChatNextStep(params, nextStep, currentPayload, agentRun, currentStep);
+    }
+    /**
+     * P3 — ban the bare model Retry in CODE, not in prose.
+     *
+     * The framework's unproductive-retry cap only counts retries that carry an
+     * errorMessage (base-agent: `step==='Retry' && !terminate && !!errorMessage`).
+     * A model that emits a naked Retry is therefore exempt — that exemption is
+     * what let the 2026-08-05/06 loops run until the heap died. The prompt now
+     * forbids Retry, but a prompt is advice; this is the enforcement.
+     *
+     * Framework-generated retries are legitimate and must pass through: action
+     * results, artifact tools, context recovery and FinalPayloadValidation all
+     * carry retryInstructions or an errorMessage.
+     */
+    async validateRetryNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
+        if (!nextStep.errorMessage && !nextStep.retryInstructions) {
+            LogError('OnboardingShell: demoting a bare model-emitted Retry to Chat — this agent has no state a retry advances');
+            const spoken = nextStep.message;
+            return {
+                ...nextStep,
+                step: 'Chat',
+                terminate: true,
+                message: spoken && spoken.trim().length > 0
+                    ? spoken
+                    : "Let me make sure I've got that — tell me a bit more and I'll fold it in.",
+            };
+        }
+        return super.validateRetryNextStep(params, nextStep, currentPayload, agentRun, currentStep);
+    }
+    /**
+     * P1 — read the founder's ACTUAL answer to the approval form.
+     *
+     * A depth-0 Chat step with a responseForm creates an `MJ: AI Agent Requests`
+     * row carrying the form schema; the founder's reply lands in `Response`.
+     * Reading it is the deterministic equivalent of Skip's
+     * IntentDetector.checkFormResponseForApproval, which parses the form token
+     * and lets an explicit choice BLOCK any LLM re-interpretation. Until now
+     * nothing in this app read that answer at all — the approve/revise buttons
+     * were decoration.
+     */
+    async readPriorFormAnswer(params) {
+        if (!params.lastRunId)
+            return null;
+        try {
+            const rv = new RunView();
+            const res = await rv.RunView({
+                EntityName: 'MJ: AI Agent Requests',
+                ExtraFilter: `OriginatingAgentRunID='${params.lastRunId}'`,
+                Fields: ['Response', 'Status'],
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: 1,
+                ResultType: 'simple',
+            }, params.contextUser);
+            const row = res.Success ? res.Results?.[0] : null;
+            if (!row?.Response)
+                return null;
+            const parsed = JSON.parse(row.Response);
+            return parsed && typeof parsed === 'object' ? parsed : null;
+        }
+        catch {
+            return null; // a malformed answer must never break the interview
+        }
+    }
+    /**
+     * Read the founder's form answer from where Explorer ACTUALLY delivers it.
+     *
+     * A responseForm click does not fill `MJ: AI Agent Requests`.`Response`
+     * (verified live: every row stays `Requested`/NULL). It arrives as a USER
+     * conversation message whose body is `@`-prefixed JSON:
+     *
+     *   @{"_mode":"form","action":"formSubmit","fields":[
+     *       {"name":"action","value":"approved",...},
+     *       {"name":"feedback","value":null,...}]}
+     *
+     * Note the outer `action` is the transport verb ("formSubmit") — the
+     * founder's answer lives in `fields[]`. This flattens those into the
+     * {action, feedback, ...} record the approval flow reads. The most recent
+     * form answer wins; founder chit-chat after it does not cancel it (the
+     * materialized-once guard makes a re-applied approve a no-op).
+     */
+    async readFormAnswerFromConversation(params) {
+        // Read the stored rows, NOT params.conversationMessages. The
+        // conversation layer replaces a form message's raw JSON with its
+        // display text before the agent runs (verified live: the prompt
+        // payload for an approve turn contains zero occurrences of "_mode"
+        // while the ConversationDetail row carries the full formSubmit JSON).
+        // The in-memory transcript is a rendering; the table is the truth.
+        const conversationId = this.AgentRun?.ConversationID ?? null;
+        if (!conversationId)
+            return this.readFormAnswerFromTranscript(params);
+        try {
+            const rv = new RunView();
+            const res = await rv.RunView({
+                EntityName: 'MJ: Conversation Details',
+                ExtraFilter: `ConversationID='${conversationId}' AND Role='User'`,
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: 10,
+                Fields: ['Message'],
+                ResultType: 'simple',
+            }, params.contextUser);
+            if (!res.Success) {
+                LogError(`OnboardingShell: form-answer read failed (${res.ErrorMessage}) — falling back to transcript scan`);
+                return this.readFormAnswerFromTranscript(params);
+            }
+            for (const row of res.Results ?? []) {
+                if (!row.Message)
+                    continue;
+                const flattened = this.parseFormSubmitMessage(row.Message);
+                if (flattened) {
+                    LogStatus(`OnboardingShell: form answer from ConversationDetail — keys [${Object.keys(flattened).join(', ')}], action=${String(flattened.action ?? '(none)')}`);
+                    return flattened;
+                }
+            }
+            LogStatus('OnboardingShell: no formSubmit among the latest user messages');
+            return null;
+        }
+        catch (err) {
+            LogError(`OnboardingShell: form-answer read threw (${err instanceof Error ? err.message : err}) — falling back to transcript scan`);
+            return this.readFormAnswerFromTranscript(params);
+        }
+    }
+    /** Fallback only: scan the in-memory transcript (known to be display-text in Explorer). */
+    readFormAnswerFromTranscript(params) {
+        const userMessages = (params.conversationMessages ?? []).filter(m => m.role === 'user');
+        for (let i = userMessages.length - 1; i >= 0; i--) {
+            const raw = typeof userMessages[i].content === 'string'
+                ? userMessages[i].content
+                : userMessages[i].content
+                    .map(b => b.type === 'text' ? (b.content ?? '') : '').join(' ');
+            const flattened = this.parseFormSubmitMessage(raw);
+            if (flattened)
+                return flattened;
+        }
+        return null;
+    }
+    /** Parse one message as an Explorer formSubmit; null if it isn't one. */
+    parseFormSubmitMessage(raw) {
+        const text = raw.trim();
+        if (!text.includes('"_mode"') || !text.includes('"form"'))
+            return null;
+        try {
+            const jsonText = text.startsWith('@') ? text.slice(1) : text;
+            const parsed = JSON.parse(jsonText);
+            if (!parsed || typeof parsed !== 'object')
+                return null;
+            const obj = parsed;
+            if (obj._mode !== 'form' || !Array.isArray(obj.fields))
+                return null;
+            const out = {};
+            for (const f of obj.fields) {
+                if (f && typeof f === 'object'
+                    && typeof f.name === 'string') {
+                    out[f.name] = f.value;
+                }
+            }
+            return out;
+        }
+        catch {
+            return null; // a malformed form message must never break the interview
+        }
+    }
+    /**
+     * P1 — finalize intent, derived fresh EVERY turn and never latched.
+     *
+     * The previous one-way flag meant a single false positive disabled grilling
+     * and the messaging gate permanently. Skip's rules, ported: a long message
+     * is almost always a change request, and "approval + but…" is a change
+     * request, so negations and hedges near the trigger disqualify it.
+     */
+    founderAskedToFinalize(params) {
+        const last = (params.conversationMessages ?? []).filter(m => m.role === 'user').pop();
+        if (!last)
+            return false;
+        const text = (typeof last.content === 'string'
+            ? last.content
+            : last.content.map(b => b.type === 'text' ? b.content : '').join(' ')).trim();
+        if (!text)
+            return false;
+        // Long replies are answers, not sign-offs (Skip: "True approvals are SHORT").
+        if (text.length > 240)
+            return false;
+        const trigger = /\b(finali[sz]e|wrap (it |this )?up|we're done|that's everything)\b/i;
+        const m = trigger.exec(text);
+        if (!m)
+            return false;
+        const around = text.slice(Math.max(0, m.index - 40), m.index + m[0].length + 40);
+        if (/\b(not|don'?t|isn'?t|before we|unless|when we|once we|after we)\b/i.test(around))
+            return false;
+        return true;
+    }
+    /**
+     * P15 — keep the giant blobs out of the step log.
+     *
+     * MJ serializes the payload into PayloadAtStart/PayloadAtEnd on EVERY step.
+     * Ours carries whole scraped pages in `rawSources[].text`, the accumulated
+     * founder transcript, and the fully rendered strategy markdown — so a long
+     * interview writes megabytes of duplicated text per turn. Skip does the
+     * same projection on its two heaviest agents (base-skip-agent
+     * shouldSummarizePayload / summarizePayload).
+     *
+     * This affects LOGGING ONLY. The live payload is untouched.
+     */
+    serializePayloadAtStart(payload) {
+        return this.summarizeForLog(payload);
+    }
+    serializePayloadAtEnd(payload) {
+        return this.summarizeForLog(payload);
+    }
+    summarizeForLog(payload) {
+        if (!payload || typeof payload !== 'object')
+            return payload ? JSON.stringify(payload) : null;
+        try {
+            const clone = { ...payload };
+            if (Array.isArray(clone.rawSources)) {
+                clone.rawSources = clone.rawSources.map(src => {
+                    if (!src || typeof src !== 'object')
+                        return src;
+                    const e = src;
+                    const text = typeof e.text === 'string' ? e.text : '';
+                    return { ...e, text: `[${text.length} chars elided for logging]` };
+                });
+            }
+            const spec = clone.spec;
+            if (spec && typeof spec.displayMarkdown === 'string') {
+                clone.spec = { ...spec, displayMarkdown: `[${spec.displayMarkdown.length} chars elided for logging]` };
+            }
+            for (const k of ['guidanceOnboardingQuestions', 'augmentedBusinessObjective']) {
+                const v = clone[k];
+                if (typeof v === 'string' && v.length > 2000)
+                    clone[k] = `${v.slice(0, 2000)}…[${v.length} chars total]`;
+            }
+            return JSON.stringify(clone);
+        }
+        catch {
+            return JSON.stringify(payload);
+        }
+    }
+    /** Mark derived turns consumed — only after a synthesis has ingested them. */
+    commitConsumedTurns(payload, evidence) {
+        const consumed = asStringArray(payload.consumedUserTurns);
+        const locators = evidence.filter(e => e.channel === 'interview').map(e => e.locator);
+        if (locators.length > 0) {
+            payload.consumedUserTurns = Array.from(new Set([...consumed, ...locators]));
+        }
+    }
+    /**
+     * Deterministic finalize-intent detection on the LATEST founder message
+     * only (not history — an early "we'll finalize later" must not trigger).
+     * The LLM-set payload flag is the primary channel; this catches the
+     * explicit phrasings even when the LLM fails to set it.
+     */
+    latestUserMessageRequestsFinalize(params) {
+        const last = (params.conversationMessages ?? []).filter(m => m.role === 'user').pop();
+        if (!last)
+            return false;
+        const text = typeof last.content === 'string'
+            ? last.content
+            : last.content.map(b => b.type === 'text' ? b.content : '').join(' ');
+        return /\b(finali[sz]e|wrap (it |this )?up|we're done|that's everything)\b/i.test(text);
+    }
+    /** The deterministic onboarding shell. Fail-open: an error here logs and lets the turn proceed undirected. */
+    async runOnboardingShell(payload, params) {
+        if (!payload || !params.contextUser)
+            return;
+        // Runaway guard. The prompt's staging contract ends in `step: "Retry"`,
+        // so ANY turn where the shell fails to move the state forward becomes an
+        // infinite prompt loop that ends in an OOM crash (2026-08-06 incident;
+        // the 2026-08-05 one was the same shape). Count shell passes within the
+        // run and hand control back to the founder well before the framework's
+        // iteration ceiling.
+        // Per-RUN, not per-conversation: the payload round-trips between turns,
+        // so the counter has to reset when a new run starts or a normal
+        // multi-turn interview would trip the cap and halt itself.
+        const runId = this.AgentRun?.ID ?? null;
+        if (payload.shellRunId !== runId) {
+            payload.shellRunId = runId;
+            payload.shellTurns = 0;
+        }
+        const shellTurns = asNumber(payload.shellTurns) + 1;
+        payload.shellTurns = shellTurns;
+        if (shellTurns > MAX_SHELL_PASSES_PER_RUN) {
+            payload.rawSources = [];
+            this.publishState(payload, {
+                phase: 'Blocked',
+                note: `The interview engine ran ${shellTurns} passes in one turn without settling. Summarize what you have and ask the founder one question.`,
+            });
+            return;
+        }
+        // Either location is durable; prefer the published state so the model's
+        // view and the shell's view are read from one place.
+        const priorState = payload.onboarding;
+        const claimed = typeof payload.brandId === 'string'
+            ? payload.brandId
+            : (typeof priorState?.brandId === 'string' ? priorState.brandId : undefined);
+        // SECURITY: anything in the payload may have been written by the model
+        // (it returns payloadChangeRequests). A brand id is a SCOPE, so accept
+        // it only if it is one of this caller's authorized brands — otherwise a
+        // model that names a sibling brand could widen its own access.
+        let brandId = claimed && this.isAuthorizedBrand(payload, claimed) ? claimed : undefined;
+        if (claimed && !brandId) {
+            LogError(`OnboardingShell: ignoring unauthorized brandId in payload (${claimed}) — not among the caller's grants`);
+            payload.brandId = undefined;
+        }
+        if (brandId) {
+            payload.brandId = brandId;
+            if (typeof payload.brandName !== 'string') {
+                await this.hydrateBrandContext(payload, params.contextUser);
+                brandId = typeof payload.brandId === 'string' ? payload.brandId : brandId;
+            }
+        }
+        if (!brandId) {
+            const named = this.resolveBrandFromConversation(payload, params);
+            if (named) {
+                payload.brandId = named;
+                // Late resolution: pull brandName + the derived parent companyId
+                // from the Brand row the same way the base ladder would have.
+                // (Clears payload.brandId again if the row doesn't resolve.)
+                await this.hydrateBrandContext(payload, params.contextUser);
+                brandId = typeof payload.brandId === 'string' ? payload.brandId : undefined;
+            }
+        }
+        if (!brandId) {
+            // No brand = no snapshot = no directive. Say so explicitly instead
+            // of leaving the prompt undirected, which loops on the staging rule.
+            payload.rawSources = [];
+            const choices = this.brandChoiceLabels(payload);
+            this.publishState(payload, {
+                phase: 'AwaitingBrand',
+                brandChoices: choices,
+                note: choices.length > 0
+                    ? 'Which brand this strategy is for has not been established yet.'
+                    : 'No brand is resolved and this user has no authorized brands visible.',
+            });
+            return;
+        }
+        payload.shellError = null;
+        // brandName feeds the spec header, artifact name, and approval-task
+        // title. hydrateBrandContext normally sets it; fall back to the
+        // authorized-brand list (it carries names) so it never sticks at the
+        // 'the brand' placeholder once the brand is known.
+        if (typeof payload.brandName !== 'string' && Array.isArray(payload.authorizedBrands)) {
+            const match = payload.authorizedBrands.find((b) => !!b && typeof b === 'object' && b.brandId === brandId);
+            if (match && typeof match.name === 'string' && match.name.trim())
+                payload.brandName = match.name.trim();
+        }
+        // Refresh a spec that was created before the brand resolved — the
+        // placeholder header must never survive once the real name is known.
+        const specEarly = payload.spec;
+        if (specEarly && typeof payload.brandName === 'string' && payload.brandName.trim() && specEarly.brandName !== payload.brandName) {
+            specEarly.brandName = payload.brandName;
+            specEarly.name = `${payload.brandName} — Marketing Strategy`;
+            if (specEarly.readiness !== 'approved') {
+                specEarly.description = `Draft marketing strategy for ${payload.brandName}, produced by the strategy onboarding interview.`;
+            }
+            specEarly.displayMarkdown = renderSpecMarkdown(specEarly);
+        }
+        // P1 — the founder's explicit form answer outranks everything, and
+        // finalize intent is recomputed every turn rather than latched.
+        // The conversation is the real delivery channel for form clicks; the
+        // AgentRequest read is kept as a fallback for transports that do fill
+        // `Response` (it was the ONLY read until the live approve proved the
+        // rows stay NULL and the approval was silently ignored).
+        const formAnswer = await this.readFormAnswerFromConversation(params)
+            ?? await this.readPriorFormAnswer(params);
+        const formAction = typeof formAnswer?.action === 'string' ? formAnswer.action : null;
+        const formFeedback = typeof formAnswer?.feedback === 'string' ? formAnswer.feedback.trim() : '';
+        payload.founderApproved = formAction === 'approved';
+        // Notes typed alongside an approval are approval provenance, not a
+        // revision request — they get stamped on the published version.
+        if (formAction === 'approved' && formFeedback)
+            payload.approvalNotes = formFeedback;
+        if (formAction === 'revise') {
+            // An explicit "revise" is a change request — it must clear any
+            // finalize intent, not sit alongside it.
+            payload.founderRequestedFinalize = false;
+            if (formFeedback) {
+                payload.augmentedBusinessObjective =
+                    `${String(payload.augmentedBusinessObjective ?? '')}\n[Founder revision request]: ${formFeedback}`.trim();
+            }
+        }
+        else {
+            payload.founderRequestedFinalize = this.founderAskedToFinalize(params);
+        }
+        try {
+            const state = {
+                brandId,
+                grillTurnsSinceLastSynth: asNumber(payload.grillTurnsSinceLastSynth),
+                lastSynthSectionKey: typeof payload.lastSynthSectionKey === 'string' ? payload.lastSynthSectionKey : null,
+                sectionsAlreadyResynthed: asStringArray(payload.sectionsAlreadyResynthed),
+                messagingGrillTurns: asNumber(payload.messagingGrillTurns),
+                founderRequestedFinalize: payload.founderRequestedFinalize === true,
+                founderApproved: payload.founderApproved === true
+                    || payload.spec?.readiness === 'approved',
+                sectionAskCounts: asAskCounts(payload.sectionAskCounts),
+            };
+            // Evidence is derived HERE, in code — the prompt is never asked to
+            // stage it and hand control back. (The old contract was "LLM writes
+            // payload.rawSources, returns Retry, shell synthesizes"; a Retry that
+            // carries no errorMessage is exempt from the framework's
+            // unproductive-retry cap, so any turn where the shell failed to
+            // advance looped until the heap died. Twice.)
+            const evidence = [...asEvidence(payload.rawSources), ...this.deriveInterviewEvidence(payload, params)];
+            const objective = String(payload.augmentedBusinessObjective ?? payload.businessObjective ?? '');
+            const agentRunId = this.AgentRun?.ID ?? null;
+            let snapshot = await getOnboardingSnapshot(brandId, params.contextUser);
+            let decision = decideOnboardingStep(snapshot, state);
+            // Pre-approval gate (shell half): if the founder tried to finalize or approve
+            // past a Foundation that has no draft section, withdraw that intent — on the
+            // payload AND on the state any re-decision below reads — so nothing publishes
+            // until the missing sections exist and the document is re-presented.
+            if (decision.absentSections.length > 0 && (payload.founderApproved === true || payload.founderRequestedFinalize === true)) {
+                payload.founderApproved = false;
+                payload.founderRequestedFinalize = false;
+                state.founderApproved = false;
+                state.founderRequestedFinalize = false;
+                LogStatus(`OnboardingShell: finalize/approval withheld — ${decision.absentSections.join(', ')} have no draft section yet; synthesizing first`);
+            }
+            // BATCHED-QUESTION OVERRIDE.
+            // decideOnboardingStep still counts grill turns one-question-at-a-time
+            // (GRILL_BUDGET turns per section before a re-synth). We now ask every
+            // Weak section in ONE responseForm, so a single founder reply answers
+            // what used to take several turns — and waiting for another round
+            // leaves fresh, high-signal answers unused while the agent asks again.
+            // When the founder has just supplied interview evidence and anything
+            // is still Weak, synthesize NOW.
+            const freshInterview = evidence.some(e => e.channel === 'interview');
+            if (freshInterview && decision.nextAction === 'grill' && payload.synthesisDisabled !== true) {
+                LogStatus('OnboardingShell: fresh founder answers — re-synthesizing instead of grilling again');
+                decision = { ...decision, nextAction: 'synthesize-foundations' };
+            }
+            // Failure cap: after 2 failed synthesis attempts, disable automatic
+            // synthesis for this conversation and clear the staged evidence so the
+            // prompt's "return Retry" instruction can't loop (the 240-iteration
+            // burn of 2026-08-05 is the incident this guards).
+            const synthesisDisabled = payload.synthesisDisabled === true;
+            const wantsSynthesis = decision.nextAction === 'synthesize-foundations' || decision.nextAction === 'synthesize-strategy-section';
+            if (wantsSynthesis && !synthesisDisabled && asNumber(payload.synthesisAttempts) >= 2) {
+                payload.synthesisDisabled = true;
+                payload.rawSources = [];
+                payload.shellError = 'Automatic synthesis disabled after 2 failed attempts — continue the interview manually and flag the infrastructure issue.';
+                LogError('OnboardingShell: synthesis disabled after 2 failed attempts');
+            }
+            if (decision.nextAction === 'synthesize-foundations' && evidence.length > 0 && payload.synthesisDisabled !== true) {
+                LogStatus(`OnboardingShell: running foundation synthesis (${evidence.length} evidence source(s))`);
+                payload.synthesisAttempts = asNumber(payload.synthesisAttempts) + 1;
+                // Only re-persist sections that are still Weak. A first
+                // synthesis has no snapshot to protect (weakSections is empty
+                // and every slot is new), so the guard applies solely to
+                // re-synthesis — where overwriting a settled section can lose
+                // detail the founder already gave us.
+                // …and only when those settled sections live on the DRAFT being written: an
+                // Active-version snapshot (no draft yet) describes the live strategy, and
+                // protecting its sections skips them on the new, empty draft — the 2026-09-16
+                // re-onboarding persisted one section and finalized with six missing.
+                const protectSettled = snapshot.versionStatus === 'Draft' && (snapshot.sections ?? []).length > 0;
+                const summary = await synthesizeFoundations({
+                    brandId, evidence, businessObjective: objective, agentRunId,
+                    onlySections: protectSettled ? decision.weakSections : undefined,
+                    contextUser: params.contextUser,
+                });
+                payload.synthesisAttempts = 0;
+                payload.lastSynthesis = {
+                    type: 'foundations',
+                    documentId: summary.documentId,
+                    versionId: summary.versionId,
+                    versionNumber: summary.versionNumber,
+                    // P11: persisted travels with the result — narrating a
+                    // section that failed to save is a fabrication the model
+                    // cannot otherwise detect.
+                    sections: summary.sections.map(s => ({ sectionKey: s.sectionKey, confidence: s.confidence, persisted: s.persisted })),
+                    missing: summary.missing,
+                    weakFieldCount: summary.weakFieldCount,
+                };
+                this.mergeSpec(payload, brandId, summary.sections, evidence);
+                this.commitConsumedTurns(payload, evidence);
+                payload.rawSources = [];
+                payload.synthesizedAt = new Date().toISOString();
+                payload.grillTurnsSinceLastSynth = 0;
+                snapshot = await getOnboardingSnapshot(brandId, params.contextUser);
+                decision = decideOnboardingStep(snapshot, { ...state, grillTurnsSinceLastSynth: 0 });
+            }
+            else if (decision.nextAction === 'synthesize-strategy-section' && payload.synthesisDisabled !== true) {
+                const sectionKey = String(decision.nextActionParams?.SectionKey ?? '');
+                LogStatus(`OnboardingShell: re-synthesizing section '${sectionKey}'`);
+                payload.synthesisAttempts = asNumber(payload.synthesisAttempts) + 1;
+                const result = await synthesizeSection({ brandId, evidence, businessObjective: objective, sectionKey, agentRunId, contextUser: params.contextUser });
+                payload.synthesisAttempts = 0;
+                payload.lastSynthesis = {
+                    type: 'section',
+                    sectionKey,
+                    confidence: result.confidence,
+                    skippedStrong: result.skippedStrong ?? false,
+                };
+                this.mergeSpec(payload, brandId, result.persisted ? [result] : [], evidence);
+                this.commitConsumedTurns(payload, evidence);
+                payload.rawSources = [];
+                payload.lastSynthSectionKey = sectionKey;
+                payload.sectionsAlreadyResynthed = Array.from(new Set([...state.sectionsAlreadyResynthed, sectionKey]));
+                payload.grillTurnsSinceLastSynth = 0;
+                snapshot = await getOnboardingSnapshot(brandId, params.contextUser);
+                decision = decideOnboardingStep(snapshot, {
+                    ...state,
+                    grillTurnsSinceLastSynth: 0,
+                    lastSynthSectionKey: sectionKey,
+                    sectionsAlreadyResynthed: [...state.sectionsAlreadyResynthed, sectionKey],
+                });
+            }
+            // Plan synthesis (P1–P5) runs when the Foundations settle, before
+            // approval is requested — the plan is part of what the founder
+            // approves. Slot-completeness (not a one-shot flag) gates it, so a
+            // slot that failed to parse/persist retries on the next finalize
+            // pass instead of being silently lost.
+            const planSpec = payload.spec;
+            const missingPlanKeys = PLAN_KEYS.filter(k => !planSpec?.plan?.[k]);
+            if (decision.nextAction === 'finalize-strategy-onboarding' && missingPlanKeys.length > 0 && payload.synthesisDisabled !== true) {
+                try {
+                    LogStatus(`OnboardingShell: synthesizing Plan sections (${missingPlanKeys.join(', ')})`);
+                    const planResult = await synthesizePlan({ brandId, businessObjective: objective, agentRunId, keys: missingPlanKeys, contextUser: params.contextUser });
+                    const spec = payload.spec;
+                    if (spec) {
+                        for (const ps of planResult.sections) {
+                            if (!ps.persisted)
+                                continue;
+                            spec.plan[ps.planKey] = {
+                                fields: ps.fields,
+                                narrative: ps.narrative,
+                                confidence: ps.confidence ?? 'Weak',
+                            };
+                        }
+                        spec.displayMarkdown = renderSpecMarkdown(spec);
+                    }
+                    payload.planSynthesizedAt = new Date().toISOString();
+                    payload.lastPlanSynthesis = {
+                        sections: planResult.sections.map(x => ({ planKey: x.planKey, confidence: x.confidence, persisted: x.persisted })),
+                    };
+                }
+                catch (planErr) {
+                    LogError(`OnboardingShell: plan synthesis failed (finalize proceeds without plan): ${planErr instanceof Error ? planErr.message : planErr}`);
+                }
+            }
+            // M2.2: the finalize step flips the spec to ready-for-review and
+            // raises the founder's approval Task exactly once per conversation.
+            if (decision.nextAction === 'finalize-strategy-onboarding' && !payload.approvalRequestId) {
+                try {
+                    const spec = payload.spec;
+                    if (spec) {
+                        spec.readiness = 'ready-for-review';
+                        spec.displayMarkdown = renderSpecMarkdown(spec);
+                    }
+                    const weak = decision.weakSections.length > 0 ? `Weak sections at approval time: ${decision.weakSections.join(', ')}.` : 'All sections Strong/Moderate.';
+                    const { requestId } = await createStrategyApprovalRequest({
+                        brandId,
+                        brandName: typeof payload.brandName === 'string' ? payload.brandName : 'the brand',
+                        strategyDocumentId: payload.lastSynthesis?.documentId ?? null,
+                        summary: `The strategy-onboarding interview is complete. ${weak} Review the latest Marketing Strategy artifact in the onboarding conversation.`,
+                        agentRunId,
+                        contextUser: params.contextUser,
+                    });
+                    payload.approvalRequestId = requestId;
+                }
+                catch (taskErr) {
+                    LogError(`OnboardingShell: approval-task creation failed (finalize proceeds): ${taskErr instanceof Error ? taskErr.message : taskErr}`);
+                }
+            }
+            // M2.3 — the founder approved, so PUBLISH.
+            //
+            // Until now the approve button only flipped a payload flag. The
+            // version stayed Draft, every section stayed unapproved, the task
+            // stayed Open, and the agent still announced the strategy was live
+            // — a fabricated success at the one moment the founder acts on it.
+            // Guarded on the materialized id alone (not on the error), so a
+            // transient failure retries if the founder speaks again.
+            if (decision.nextAction === 'complete' && !payload.materializedVersionId) {
+                await this.materializeApprovedStrategy(payload, brandId, params);
+                if (payload.materializationError) {
+                    // A refused publish must not end the interview: withdraw the approval and
+                    // re-present the document (ReadyForApproval), with the refusal as the
+                    // engine note the prompt reads — the founder fixes the gap in THIS
+                    // conversation instead of starting over.
+                    payload.founderApproved = false;
+                    decision = {
+                        ...decision,
+                        phase: 'Finalize',
+                        nextAction: 'finalize-strategy-onboarding',
+                        rationale: `Publishing was refused and the strategy remains Draft: ${payload.materializationError}`,
+                    };
+                }
+            }
+            // P4 — the shell owns the flow-control counters.
+            // These feed GRILL_BUDGET and the messaging must-ask gate inside
+            // decideOnboardingStep. They used to be incremented by the MODEL on
+            // request, so a model that forgot meant the budget never fired and
+            // the interview could never finalize; one that over-counted
+            // finalized early. Skip's equivalent move: compute the flag in code
+            // and tell the model it was done for them.
+            if (decision.nextAction === 'grill') {
+                payload.grillTurnsSinceLastSynth = asNumber(payload.grillTurnsSinceLastSynth) + 1;
+                // Per-section ask budget. We ask about every unsettled section
+                // in one batched form, so each of them has been pressed once —
+                // charge them all, or the budget never fires and the section
+                // that can't be answered is re-asked forever.
+                const askCounts = asAskCounts(payload.sectionAskCounts);
+                for (const key of decision.weakSections)
+                    askCounts[key] = (askCounts[key] ?? 0) + 1;
+                payload.sectionAskCounts = askCounts;
+                const targeted = String(decision.nextActionParams?.SectionKey ?? '');
+                if (targeted === MESSAGING_SECTION_KEY || decision.weakSections.includes(MESSAGING_SECTION_KEY)) {
+                    payload.messagingGrillTurns = asNumber(payload.messagingGrillTurns) + 1;
+                }
+            }
+            const settled = (snapshot.sections ?? [])
+                .filter(s => s.confidenceLevel === 'Strong' || s.confidenceLevel === 'Moderate')
+                .map(s => s.sectionKey);
+            // The named gaps for everything still unsettled. This is what makes
+            // the questions land on the blocker: the engine knows Market
+            // Context is short a growth_rate, so the prompt can ask for THAT
+            // rather than circling the section for four rounds.
+            const gaps = (snapshot.sections ?? [])
+                .filter(s => decision.weakSections.includes(s.sectionKey))
+                .filter(s => (s.missingFields?.length ?? 0) > 0)
+                .map(s => ({ sectionKey: s.sectionKey, missing: [...(s.missingFields ?? [])] }));
+            this.publishState(payload, {
+                phase: PHASE_BY_ACTION[decision.nextAction] ?? 'Gather',
+                gaps,
+                weakSections: [...decision.weakSections],
+                settledSections: settled,
+                note: decision.rationale,
+            });
+        }
+        catch (e) {
+            // Fail-visible, not fail-open: an unexplained shell error used to
+            // leave the prompt with no state at all, which is the hole the
+            // runaway loop fell through.
+            LogError(`OnboardingShell: ${e instanceof Error ? e.message : String(e)}`);
+            payload.shellError = e instanceof Error ? e.message : String(e);
+            this.publishState(payload, {
+                phase: 'Blocked',
+                note: 'The onboarding engine hit an error this turn. Tell the founder plainly, and ask a question you can act on next turn.',
+            });
+        }
+    }
+    /**
+     * Button-group labels for the AwaitingBrand phase. Two brands of DIFFERENT
+     * companies can share a name, so a repeated name is qualified with its
+     * company — otherwise the founder is asked to choose between two identical
+     * buttons.
+     */
+    brandChoiceLabels(payload) {
+        const brands = (Array.isArray(payload.authorizedBrands) ? payload.authorizedBrands : [])
+            .filter((b) => !!b && typeof b === 'object');
+        const names = brands
+            .map(b => (typeof b.name === 'string' ? b.name.trim() : ''))
+            .filter(n => n.length > 0);
+        const seen = new Map();
+        for (const n of names)
+            seen.set(n.toLowerCase(), (seen.get(n.toLowerCase()) ?? 0) + 1);
+        const labels = [];
+        for (const b of brands) {
+            const name = typeof b.name === 'string' ? b.name.trim() : '';
+            if (!name)
+                continue;
+            const company = typeof b.companyName === 'string' ? b.companyName.trim() : '';
+            labels.push((seen.get(name.toLowerCase()) ?? 0) > 1 && company ? `${name} (${company})` : name);
+        }
+        return labels;
+    }
+    /**
+     * Publish the turn's STATE — never a command.
+     *
+     * Skip's agents don't take injected imperatives: their prompts branch on
+     * payload the model can see and verify (`{% if _CURRENT_PAYLOAD.changeRequest %}`),
+     * and `preparePromptParams` only ever adds evidence. A directive is a
+     * second control channel with no defined behavior when it's absent — which
+     * is exactly how a turn with no directive fell through to "gather and
+     * Retry" and looped. State always has a branch.
+     */
+    /**
+     * M2.3 — turn the founder's approval into published state.
+     *
+     * Runs in the shell, never as an LLM tool choice: approval is a boundary
+     * the model may narrate but must not decide. This calls the
+     * materialization SERVICE directly rather than the `Materialize Strategy
+     * Version` action — an action invoking another action is the documented
+     * anti-pattern, and that action is only the founder/UI/tasks-flow entry
+     * point onto this same call.
+     *
+     * Every outcome lands on the payload so the prompt can branch on what
+     * actually happened rather than on what it hoped happened.
+     */
+    async materializeApprovedStrategy(payload, brandId, params) {
+        const conversationId = this.AgentRun?.ConversationID ?? null;
+        if (!conversationId) {
+            payload.materializationError = 'No conversation on the agent run — cannot resolve the approved artifact version.';
+            LogError(`OnboardingShell: ${payload.materializationError}`);
+            return;
+        }
+        const artifactVersionId = await this.resolveApprovedArtifactVersionId(conversationId, params.contextUser);
+        if (!artifactVersionId) {
+            payload.materializationError = 'No strategy artifact version found in this conversation to publish.';
+            LogError(`OnboardingShell: ${payload.materializationError}`);
+            return;
+        }
+        const approvalNotes = typeof payload.approvalNotes === 'string' ? payload.approvalNotes : null;
+        try {
+            const result = await materializeStrategyVersion({
+                brandId,
+                artifactVersionId,
+                approvedByUserId: params.contextUser.ID,
+                approvalNotes,
+                contextUser: params.contextUser,
+            });
+            payload.materializedVersionId = result.versionId;
+            payload.materializedVersionNumber = result.versionNumber;
+            payload.materializedSections = result.sectionsWritten;
+            payload.materializationError = undefined;
+            // Stamp the working spec, in CODE (the contract: "approved is set by the
+            // materialization step, never by an agent"). Until now nothing did — the
+            // run's own artifact kept saying ready-for-review and the viewer kept
+            // showing "Draft — not yet materialized" on the very message announcing
+            // the publish. The stamp also makes the interview's terminal state
+            // (readiness === 'approved') reachable on any later turn.
+            const publishedSpec = payload.spec;
+            if (publishedSpec) {
+                publishedSpec.readiness = 'approved';
+                publishedSpec.materialization = {
+                    strategyDocumentId: result.documentId,
+                    strategyDocumentVersionId: result.versionId,
+                    versionNumber: result.versionNumber,
+                    materializedAt: new Date().toISOString(),
+                };
+                // The header said "Draft marketing strategy…" under an APPROVED badge.
+                publishedSpec.description = `Marketing strategy for ${publishedSpec.brandName} — approved and published as version ${result.versionNumber}.`;
+                publishedSpec.displayMarkdown = renderSpecMarkdown(publishedSpec);
+            }
+            LogStatus(`OnboardingShell: strategy v${result.versionNumber} is now Active — ${result.sectionsWritten} section(s) materialized, ${result.supersededVersions} superseded.`);
+        }
+        catch (err) {
+            payload.materializationError = err instanceof Error ? err.message : String(err);
+            LogError(`OnboardingShell: materialization FAILED — strategy remains Draft: ${payload.materializationError}`);
+            return;
+        }
+        await this.closeApprovalTask(payload, approvalNotes, params.contextUser);
+        // The strategy → execution handoff, in code. This used to live only
+        // behind an LLM-optional action, so the first live publish wrote zero
+        // recommendations because the model simply didn't call it. Best-effort
+        // like the task ceremony: the strategy IS published; a rec failure is
+        // surfaced, never reported as a failed publish.
+        try {
+            const versionId = typeof payload.materializedVersionId === 'string' ? payload.materializedVersionId : null;
+            if (versionId) {
+                const recResult = await writeFinalizeRecommendations({
+                    brandId,
+                    strategyDocumentVersionId: versionId,
+                    agentRunId: this.AgentRun?.ID ?? null,
+                    contextUser: params.contextUser,
+                });
+                payload.finalizeRecsCreated = recResult.created;
+                if (recResult.errors.length > 0)
+                    payload.finalizeRecsError = recResult.errors.join('; ');
+            }
+        }
+        catch (recErr) {
+            payload.finalizeRecsError = recErr instanceof Error ? recErr.message : String(recErr);
+            LogError(`OnboardingShell: finalize-recommendation write failed (strategy stays published): ${payload.finalizeRecsError}`);
+        }
+    }
+    /**
+     * Complete the founder's approval Task after a successful publish.
+     *
+     * Best-effort by design: the strategy IS Active by the time this runs, so
+     * a stuck task must never turn a successful publish into a reported
+     * failure. It surfaces on its own payload key instead.
+     */
+    async closeApprovalTask(payload, approvalNotes, contextUser) {
+        const requestId = typeof payload.approvalRequestId === 'string' ? payload.approvalRequestId : null;
+        if (!requestId)
+            return;
+        try {
+            await recordStrategyApprovalDecision({
+                requestId,
+                outcomeCode: 'Approved',
+                notes: approvalNotes,
+                // This run consumed the decision (it just materialized the strategy);
+                // saying so stops core from resuming the paused originating run on top of it.
+                resumingAgentRunId: this.AgentRun?.ID ?? null,
+                contextUser,
+            });
+        }
+        catch (ceremonyErr) {
+            payload.approvalRequestError = ceremonyErr instanceof Error ? ceremonyErr.message : String(ceremonyErr);
+            LogError(`OnboardingShell: approval decision failed (strategy stays published): ${payload.approvalRequestError}`);
+        }
+    }
+    /**
+     * Resolve the newest artifact version emitted in this conversation — the
+     * snapshot the founder actually approved, and the row whose id gets
+     * stamped as ApprovedArtifactVersionID.
+     *
+     * Two hops, because the framework links artifacts through
+     * ConversationDetailArtifact and neither that entity nor
+     * `MJ: Artifact Versions` denormalizes ConversationID.
+     */
+    async resolveApprovedArtifactVersionId(conversationId, contextUser) {
+        try {
+            const rv = new RunView();
+            // Newest-first and capped: we want the LATEST artifact, so recent
+            // details are the only ones that can carry it. This also keeps the
+            // IN clause below bounded on a long conversation.
+            const details = await rv.RunView({
+                EntityName: 'MJ: Conversation Details',
+                ExtraFilter: `ConversationID='${conversationId}'`,
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: RECENT_DETAILS_SCANNED_FOR_ARTIFACT,
+                Fields: ['ID'],
+                ResultType: 'simple',
+            }, contextUser);
+            if (!details.Success) {
+                LogError(`OnboardingShell: conversation-detail lookup failed: ${details.ErrorMessage}`);
+                return null;
+            }
+            if (!details.Results?.length)
+                return null;
+            const idList = details.Results.map(d => `'${d.ID}'`).join(',');
+            const links = await rv.RunView({
+                EntityName: 'MJ: Conversation Detail Artifacts',
+                ExtraFilter: `ConversationDetailID IN (${idList})`,
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: 1,
+                Fields: ['ArtifactVersionID'],
+                ResultType: 'simple',
+            }, contextUser);
+            if (!links.Success) {
+                LogError(`OnboardingShell: artifact-link lookup failed: ${links.ErrorMessage}`);
+                return null;
+            }
+            return links.Results?.[0]?.ArtifactVersionID ?? null;
+        }
+        catch (err) {
+            LogError(`OnboardingShell: artifact-version resolution threw: ${err instanceof Error ? err.message : err}`);
+            return null;
+        }
+    }
+    publishState(payload, state) {
+        const spec = payload.spec;
+        payload.onboarding = {
+            phase: state.phase,
+            // The resolved brand is mirrored here as well as at payload.brandId.
+            // (Verified 2026-08-06 against four real runs: top-level keys the
+            // shell writes DO survive the payload round-trip — an earlier note
+            // here claimed otherwise, which was wrong. The absences that
+            // prompted that claim were turns where the shell returned early at
+            // AwaitingBrand and never wrote the key at all.)
+            // The mirror is still worth keeping: it puts the brand in the same
+            // object the template renders, so state the model sees and state
+            // the shell reads cannot drift apart.
+            brandId: typeof payload.brandId === 'string' ? payload.brandId : null,
+            brandName: typeof payload.brandName === 'string' ? payload.brandName : null,
+            weakSections: state.weakSections ?? [],
+            settledSections: state.settledSections ?? [],
+            gaps: state.gaps ?? [],
+            brandChoices: state.brandChoices ?? [],
+            synthesizedAt: payload.synthesizedAt ?? null,
+            planSynthesizedAt: payload.planSynthesizedAt ?? null,
+            approvalRequestId: payload.approvalRequestId ?? null,
+            // Publish outcome. `published` is the ONLY thing the model may
+            // treat as "the strategy is live" — it is set from the
+            // materialization result, never from the founder having clicked.
+            published: typeof payload.materializedVersionId === 'string',
+            publishedVersionNumber: payload.materializedVersionNumber ?? null,
+            publishedSections: payload.materializedSections ?? null,
+            publishError: payload.materializationError ?? null,
+            specReadiness: spec?.readiness ?? null,
+            foundationSlots: spec ? Object.keys(spec.foundations ?? {}).length : 0,
+            planSlots: spec ? Object.keys(spec.plan ?? {}).length : 0,
+            // Read-only for the template; the shell is the only writer (P4).
+            grillTurnsSinceLastSynth: asNumber(payload.grillTurnsSinceLastSynth),
+            messagingGrillTurns: asNumber(payload.messagingGrillTurns),
+            note: state.note ?? null,
+        };
+        // Retired: directedAction/directedSection/directedRationale. One channel only.
+        payload.directedAction = undefined;
+        payload.directedSection = undefined;
+        payload.directedRationale = undefined;
+    }
+    /**
+     * Maintain payload.spec — the MarketingStrategySpec working draft that
+     * artifact versions serialize (Rev 5 §2.7.1). Slots merge from synthesis
+     * results (fields + narrative + derived confidence); sources accumulate
+     * from consumed evidence; displayMarkdown re-renders via the one shared
+     * renderer so the artifact viewer's extract rule never re-derives it.
+     */
+    mergeSpec(payload, brandId, sections, evidence) {
+        const brandName = typeof payload.brandName === 'string' ? payload.brandName : 'the brand';
+        const existing = payload.spec;
+        const spec = existing ?? {
+            specVersion: 1,
+            name: `${brandName} — Marketing Strategy`,
+            description: `Draft marketing strategy for ${brandName}, produced by the strategy onboarding interview.`,
+            // MarketingStrategySpec.companyId is the brand's PARENT company —
+            // derived, never a scope (BaseMarketingAgent sets payload.companyId
+            // from Brand.CompanyID). The scope is spec.brandId, set below.
+            companyId: typeof payload.companyId === 'string' ? payload.companyId : '',
+            brandName,
+            asOfDate: (typeof payload.currentDate === 'string' ? payload.currentDate : new Date().toISOString().slice(0, 10)),
+            readiness: 'incomplete',
+            foundations: {},
+            plan: {},
+            sources: [],
+            openQuestions: [],
+        };
+        spec.brandId = brandId;
+        if (!spec.companyId && typeof payload.companyId === 'string')
+            spec.companyId = payload.companyId;
+        // The brand may resolve AFTER the spec was first created (multi-brand
+        // users start unresolved) — refresh the header fields whenever the
+        // real name is known so the placeholder never sticks.
+        if (brandName !== 'the brand' && spec.brandName !== brandName) {
+            spec.brandName = brandName;
+            spec.name = `${brandName} — Marketing Strategy`;
+            if (spec.readiness !== 'approved') {
+                spec.description = `Draft marketing strategy for ${brandName}, produced by the strategy onboarding interview.`;
+            }
+        }
+        for (const s of sections) {
+            if (!s.persisted || !isFoundationKey(s.sectionKey))
+                continue;
+            const slot = {
+                fields: s.fields,
+                narrative: s.narrative,
+                confidence: s.confidence ?? 'Weak',
+            };
+            spec.foundations[s.sectionKey] = slot;
+        }
+        const channelToKind = {
+            website: 'url', blogs: 'entity', linkedin: 'url', competitors: 'url', interview: 'interview',
+        };
+        for (const e of evidence) {
+            if (!spec.sources.some(x => x.locator === e.locator && x.kind === channelToKind[e.channel])) {
+                spec.sources.push({ kind: channelToKind[e.channel], locator: e.locator, label: e.label, retrievedAt: new Date().toISOString() });
+            }
+        }
+        spec.displayMarkdown = renderSpecMarkdown(spec);
+        payload.spec = spec;
+    }
+};
+MarketingStrategyOnboardingAgent = __decorate([
+    RegisterClass(BaseAgent, "MarketingStrategyOnboardingAgent")
+], MarketingStrategyOnboardingAgent);
+export { MarketingStrategyOnboardingAgent };
+function asNumber(v) {
+    const n = typeof v === 'number' ? v : parseInt(String(v ?? ''), 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/**
+ * Per-section ask counts off the payload. Anything malformed degrades to an
+ * empty map — a corrupt counter must relax the ask budget, never invent one.
+ */
+function asAskCounts(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(v)) {
+        const n = asNumber(raw);
+        if (n > 0)
+            out[key] = n;
+    }
+    return out;
+}
+function asStringArray(v) {
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === 'string');
+    if (typeof v === 'string' && v.trim())
+        return v.split(',').map(s => s.trim()).filter(Boolean);
+    return [];
+}
+function asEvidence(v) {
+    if (!Array.isArray(v))
+        return [];
+    const channels = new Set(['website', 'blogs', 'linkedin', 'competitors', 'interview']);
+    return v.filter((e) => e !== null && typeof e === 'object'
+        && channels.has(String(e.channel))
+        && typeof e.text === 'string'
+        && e.text.trim().length > 0);
+}
+export function LoadMarketingStrategyOnboardingAgent() { }
+//# sourceMappingURL=MarketingStrategyOnboardingAgent.js.map