dsh-scout 0.8.1 → 0.9.2

package/dist/index.js

@@ -1,44 +1,239 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import z from '@deepseek-ai/schemastery';
-import { addClaim, addSource, appendEvent, CLAIM_DIMENSIONS, CLAIM_IMPACTS, CLAIM_STATUSES, createCase, decideCase, DEFAULT_AUTHORITY_HOST_SUFFIXES, EVIDENCE_LEVELS, EXPORT_FILE_NAMES, exportCaseFiles, generateInterviewQuestions, importCaseFromFiles, inferEvidenceLevel, inferSourceType, renderComparison, renderReport, SOURCE_TYPES, verifyClaim, verifyIdentity, } from './model.js';
+import { addClaim, addSource, appendEvent, CLAIM_DIMENSIONS, CLAIM_IMPACTS, CLAIM_STATUSES, computeCoverage, createCase, decideCase, DEFAULT_AUTHORITY_HOST_SUFFIXES, EVIDENCE_LEVELS, EXPORT_FILE_NAMES, exportCaseFiles, findSourceByUrl, generateInterviewQuestions, importCaseFromFiles, inferEvidenceLevel, inferSourceType, renderComparison, renderReport, SOURCE_TYPES, verifyClaim, verifyIdentity, } from './model.js';
+import { formatScoutString, isScoutLanguage, normalizeScoutLanguage, scoutStrings, } from './i18n.js';
 export const name = 'dsh-scout';
 export const inject = ['tools'];
 export const Config = z.object({
     scoutDir: z.string().default('dsh-scout'),
     autoPersist: z.boolean().default(false),
     authorityHostSuffixes: z.array(z.string()).default([...DEFAULT_AUTHORITY_HOST_SUFFIXES]),
+    language: z.union([z.const('zh-CN'), z.const('en')]).default('zh-CN'),
+});
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+const IMPACT_RANK = { blocking: 0, material: 1, informational: 2 };
+/** Up to three smallest next actions for open blocking/material claims. */
+const deriveNextActions = (scoutCase) => [...scoutCase.claims]
+    .filter(claim => claim.impact !== 'informational' && claim.status !== 'verified')
+    .sort((left, right) => IMPACT_RANK[left.impact] - IMPACT_RANK[right.impact])
+    .map(claim => claim.nextAction.trim())
+    .filter((action, index, all) => Boolean(action) && all.indexOf(action) === index)
+    .slice(0, 3);
+const capIds = (ids, limit = 20) => ids.length > limit ? [...ids.slice(0, limit), `+${ids.length - limit} more`] : ids;
+const buildEnvelope = (scoutCase, changed, extras = {}) => {
+    const verified = scoutCase.claims.filter(claim => claim.status === 'verified').length;
+    return {
+        ok: true,
+        caseId: scoutCase.caseId,
+        decision: scoutCase.decision,
+        identity: scoutCase.subject.identityStatus,
+        counts: {
+            sources: scoutCase.sources.length,
+            claims: scoutCase.claims.length,
+            verified,
+            open: scoutCase.claims.length - verified,
+        },
+        changed: { kind: changed.kind, ids: capIds(changed.ids) },
+        nextActions: deriveNextActions(scoutCase),
+        ...(extras.persist ? { persist: extras.persist } : {}),
+        ...(extras.errors?.length ? { errors: extras.errors } : {}),
+    };
+};
+/** Model-facing render budget for one mutation summary, in UTF-8 bytes. */
+const MAX_RENDER_BYTES = 1024;
+/** Marks a clipped render. Its own byte cost is paid out of the same budget. */
+const ELLIPSIS = '…';
+/** Byte length of a JS string in UTF-8, without relying on Node globals. */
+const utf8Length = (text) => {
+    let bytes = 0;
+    for (const character of text) {
+        const code = character.codePointAt(0) ?? 0;
+        bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+};
+/**
+ * Hard cap so an oversized free-text field can never blow the render budget.
+ * The returned string — including the ellipsis, whose UTF-8 cost is derived
+ * rather than assumed — is never longer than `limit` bytes. Cutting stops on a
+ * code-unit boundary; a lone surrogate left by slicing a pair still encodes as
+ * 3 bytes, so the measured length stays the conservative one.
+ */
+const clampUtf8 = (text, limit) => {
+    if (utf8Length(text) <= limit)
+        return text;
+    const suffixBytes = utf8Length(ELLIPSIS);
+    let clipped = text;
+    while (clipped.length > 0 && utf8Length(clipped) > limit - suffixBytes)
+        clipped = clipped.slice(0, -1);
+    return `${clipped}${ELLIPSIS}`;
+};
+/** Per-field cap applied before the whole-render cap. */
+const clipField = (text, limit) => text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+const formatEnvelope = (value) => {
+    const { counts, changed } = value;
+    const lines = [
+        `[${clipField(value.caseId, 80)}] ${value.decision} · identity ${value.identity} · sources ${counts.sources} / claims ${counts.claims} (verified ${counts.verified}, open ${counts.open})`,
+        `changed: ${changed.kind}${changed.ids.length ? ` (${clipField(changed.ids.join(', '), 200)})` : ''}`,
+    ];
+    if (value.nextActions.length) {
+        lines.push(`next: ${value.nextActions.map(action => clipField(action, 140)).join(' | ')}`);
+    }
+    if (value.persist) {
+        lines.push(value.persist.persisted
+            ? `persisted: ${clipField(value.persist.targetDir, 160)}`
+            : `PERSIST FAILED (${clipField(value.persist.targetDir, 160)}): ${clipField(value.persist.error ?? 'unknown error', 160)}`);
+    }
+    if (value.errors?.length) {
+        lines.push(`rejected: ${value.errors.length} item(s) — first: ${clipField(value.errors[0].error, 160)}`);
+    }
+    if (value.sourceDir) {
+        lines.push(`imported from ${clipField(value.sourceDir, 160)} (complete: ${value.complete === true})`);
+    }
+    // The per-field caps keep this from triggering in practice; the whole-render
+    // cap is the guarantee the gate asserts. `clampUtf8` already budgets for the
+    // ellipsis it appends, so the call passes the budget itself — no slack magic
+    // number that a later edit could shrink below the suffix cost.
+    return clampUtf8(lines.join('\n'), MAX_RENDER_BYTES);
+};
+/** Envelope schema shared by every mutating tool. */
+const mutationSchema = () => ({
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ok: { type: 'boolean', required: true },
+        caseId: { type: 'string', required: true },
+        decision: {
+            type: 'string',
+            enum: ['PROCEED', 'VERIFY', 'STOP'],
+            required: true,
+        },
+        identity: {
+            type: 'string',
+            enum: ['verified', 'needs_verification'],
+            required: true,
+        },
+        counts: {
+            type: 'object',
+            additionalProperties: false,
+            required: true,
+            properties: {
+                sources: { type: 'integer', required: true },
+                claims: { type: 'integer', required: true },
+                verified: { type: 'integer', required: true },
+                open: { type: 'integer', required: true },
+            },
+        },
+        changed: {
+            type: 'object',
+            additionalProperties: false,
+            required: true,
+            properties: {
+                kind: {
+                    type: 'string',
+                    enum: [
+                        'case_started',
+                        'source_added',
+                        'sources_added',
+                        'claim_added',
+                        'claims_added',
+                        'identity_verified',
+                        'claim_verified',
+                        'case_imported',
+                        'case_rehydrated',
+                    ],
+                    required: true,
+                },
+                ids: { type: 'array', items: { type: 'string' }, required: true },
+            },
+        },
+        nextActions: { type: 'array', items: { type: 'string' }, required: true },
+        persist: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                persisted: { type: 'boolean', required: true },
+                targetDir: { type: 'string', required: true },
+                error: { type: 'string' },
+            },
+        },
+        errors: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    url: { type: 'string', required: true },
+                    error: { type: 'string', required: true },
+                },
+            },
+        },
+        sourceDir: { type: 'string' },
+        complete: { type: 'boolean' },
+    },
+});
+const mutationOutput = () => ({
+    schema: mutationSchema(),
+    render: (_args, value) => [
+        { type: 'text', text: formatEnvelope(value) },
+    ],
 });
 export function apply(ctx, config = {}) {
     const cases = new Map();
     const caseKey = (caseId, agentId) => `${String(agentId ?? 'unscoped')}::${caseId}`;
-    const requireCase = (key) => {
-        const scoutCase = cases.get(key);
-        if (!scoutCase)
-            throw new Error(`Unknown case: ${key.split('::').at(-1)}`);
-        return scoutCase;
-    };
-    // Optional host services: unavailable hosts degrade gracefully (tools report
-    // the missing service instead of failing to register).
-    const fs = ctx.get('fs');
-    const web = ctx.get('web');
+    const keyCaseId = (key) => key.slice(key.indexOf('::') + 2 || 0);
     const authoritySuffixes = config.authorityHostSuffixes ?? DEFAULT_AUTHORITY_HOST_SUFFIXES;
     const defaultScoutDir = config.scoutDir?.replace(/\/+$/, '') || 'dsh-scout';
     const caseExportDir = (caseId) => `${defaultScoutDir}/${caseId}`;
-    const persistFiles = async (scoutCase, targetDir) => {
-        if (!fs)
-            return { persisted: false, targetDir, error: 'Filesystem service is unavailable in this host' };
-        try {
-            const files = exportCaseFiles(scoutCase);
-            for (const name of EXPORT_FILE_NAMES) {
-                const target = await fs.resolve(`${targetDir}/${name}`);
-                await fs.writeText(target, files[name]);
-            }
-            return { persisted: true, targetDir };
-        }
-        catch (error) {
-            return { persisted: false, targetDir, error: error instanceof Error ? error.message : String(error) };
-        }
+    /** Resolved once from validated config; every renderer and decision follows it. */
+    const language = normalizeScoutLanguage(config.language);
+    const strings = scoutStrings(language);
+    /**
+     * Case-authored copy (objective, fit question, curated interview questions) is
+     * written in the language the case was created in. When this deployment
+     * renders in another language, the still-untouched factory defaults are
+     * swapped for this deployment's own defaults, so `case.json` never claims one
+     * language while carrying another language's prose. A value the user edited
+     * no longer equals a factory default and is deliberately left alone. Curated
+     * interview questions follow the same rule entry by entry while the set still
+     * has the factory length; a differently sized set is kept as authored.
+     */
+    const alignCaseDefaults = (scoutCase) => {
+        const declared = isScoutLanguage(scoutCase.language) ? scoutCase.language : undefined;
+        const source = scoutStrings(declared);
+        if (source.language === strings.language)
+            return scoutCase;
+        const swap = (current, from, to) => (current === from ? to : current);
+        const curated = scoutCase.interviewQuestions ?? [];
+        const factory = source.defaults.interviewQuestions;
+        const target = strings.defaults.interviewQuestions;
+        // Entry-by-entry: a question the user edited no longer equals its factory
+        // slot and is kept verbatim, while every untouched slot aligns. A set whose
+        // length differs from the factory array is taken as fully user-authored and
+        // preserved as a whole (there is no index to compare it against).
+        const alignedQuestions = curated.length === factory.length
+            ? curated.map((question, index) => (question === factory[index] ? target[index] : question))
+            : curated;
+        return {
+            ...scoutCase,
+            decisionObjective: swap(scoutCase.decisionObjective, source.defaults.decisionObjective, strings.defaults.decisionObjective),
+            role: {
+                ...scoutCase.role,
+                fitQuestion: swap(scoutCase.role.fitQuestion, source.defaults.fitQuestion, strings.defaults.fitQuestion),
+            },
+            interviewQuestions: alignedQuestions,
+        };
     };
+    const decide = (scoutCase) => ({
+        ...decideCase(alignCaseDefaults(scoutCase), { language }),
+        // Keep the case's own label in sync with the language this deployment renders in.
+        language,
+    });
+    const renderReportOf = (scoutCase) => renderReport(scoutCase, { language });
+    // Resolved per call so a later-mounted (or replaced) provider is honored.
+    const fsService = () => ctx.get('fs');
+    const webService = () => ctx.get('web');
+    const execCwd = (exec) => exec?.agent?.session?.header?.cwd;
     const recordEvent = (scoutCase, type, detail) => {
         const events = scoutCase.events ?? [];
         let n = events.length + 1;
@@ -62,54 +257,188 @@ export function apply(ctx, config = {}) {
         evidenceLevel: source.evidenceLevel,
         ingested: true,
     });
-    const maybePersist = async (scoutCase) => {
+    /* -------------------------------------------------------------- *
+     * Durable export
+     *
+     * Order is "record the event, then write": the persisted
+     * `events.jsonl` must contain the export event it belongs to.
+     * A completion marker is written last so a torn export is
+     * distinguishable from a corrupt one.
+     * -------------------------------------------------------------- */
+    const EXPORT_MARKER_FILE = 'export.complete.json';
+    const EXPORT_MARKER_SCHEMA = 'dsh-scout.export.v1';
+    const directoryOf = (displayPath) => {
+        const cut = displayPath.lastIndexOf('/');
+        return cut > 0 ? displayPath.slice(0, cut) : displayPath;
+    };
+    /**
+     * Write the five export files plus the completion marker.
+     *
+     * The marker is invalidated *before* the payload is touched and only
+     * re-asserted after every payload file landed, so an interrupted export can
+     * never leave a stale `complete: true` beside mixed-generation files.
+     */
+    const persistFiles = async (scoutCase, targetDir, fs, cwd, signal) => {
+        try {
+            const files = exportCaseFiles(scoutCase, { language });
+            const marker = (complete) => `${JSON.stringify({
+                schemaVersion: EXPORT_MARKER_SCHEMA,
+                caseId: scoutCase.caseId,
+                complete,
+                files: [...EXPORT_FILE_NAMES],
+                eventCount: (scoutCase.events ?? []).length,
+            }, null, 2)}\n`;
+            let absoluteDir;
+            const write = async (fileName, content) => {
+                const target = await fs.resolve(`${targetDir}/${fileName}`, { cwd, signal });
+                if (typeof target?.displayPath === 'string')
+                    absoluteDir = directoryOf(target.displayPath);
+                await fs.writeText(target, content, undefined, signal);
+            };
+            await write(EXPORT_MARKER_FILE, marker(false));
+            for (const fileName of EXPORT_FILE_NAMES) {
+                await write(fileName, files[fileName]);
+            }
+            await write(EXPORT_MARKER_FILE, marker(true));
+            return { persisted: true, targetDir: absoluteDir ?? targetDir };
+        }
+        catch (error) {
+            return { persisted: false, targetDir, error: messageOf(error) };
+        }
+    };
+    /**
+     * Persist a case for one tool call. On success the returned case carries
+     * the `case_exported` event that the written `events.jsonl` also has; on
+     * failure the event is dropped and the error is surfaced to the caller.
+     */
+    const exportCase = async (scoutCase, targetDir, fs, cwd, signal, auto) => {
+        const withEvent = recordEvent(scoutCase, 'case_exported', { targetDir, auto });
+        const persist = await persistFiles(withEvent, targetDir, fs, cwd, signal);
+        return { scoutCase: persist.persisted ? withEvent : scoutCase, persist };
+    };
+    const maybePersist = async (scoutCase, exec) => {
         if (!config.autoPersist)
-            return scoutCase;
-        const targetDir = caseExportDir(scoutCase.caseId);
-        const withEvent = recordEvent(scoutCase, 'case_exported', { targetDir, auto: true });
-        const result = await persistFiles(withEvent, targetDir);
-        if (!result.persisted)
-            return scoutCase;
-        return withEvent;
+            return { scoutCase };
+        const fs = fsService();
+        if (!fs) {
+            return {
+                scoutCase,
+                persist: {
+                    persisted: false,
+                    targetDir: caseExportDir(scoutCase.caseId),
+                    error: 'Filesystem service is unavailable in this host',
+                },
+            };
+        }
+        return exportCase(scoutCase, caseExportDir(scoutCase.caseId), fs, execCwd(exec), exec?.signal, true);
+    };
+    /* -------------------------------------------------------------- *
+     * Case lookup with lazy rehydration
+     * -------------------------------------------------------------- */
+    const readExportFiles = async (sourceDir, fs, cwd, signal) => {
+        const files = {};
+        for (const fileName of ['case.json', 'sources.json', 'claims.json', 'events.jsonl']) {
+            const target = await fs.resolve(`${sourceDir}/${fileName}`, { cwd, signal });
+            files[fileName] = await fs.readText(target, signal);
+        }
+        return files;
+    };
+    /**
+     * Read the completion marker. Existence is not enough: the marker is
+     * written with `complete: false` before an export starts, so a stale marker
+     * left by an interrupted export must not be read as a finished one.
+     */
+    const readCompletionMarker = async (sourceDir, fs, cwd, signal) => {
+        try {
+            const raw = await fs.readText(await fs.resolve(`${sourceDir}/${EXPORT_MARKER_FILE}`, { cwd, signal }), signal);
+            const parsed = JSON.parse(raw);
+            return parsed?.complete === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * Restore a case from `<scoutDir>/<caseId>/` when the cache misses.
+     *
+     * Only a completed export is rehydrated: an interrupted one is reported by
+     * `scout_import` (which returns `complete: false`) rather than silently
+     * becoming this session's case state. Exports written before 0.9.1 have no
+     * marker at all and must be restored explicitly with `scout_import`.
+     */
+    const rehydrate = async (caseId, key, fs, cwd, signal) => {
+        const sourceDir = caseExportDir(caseId);
+        try {
+            if (!(await readCompletionMarker(sourceDir, fs, cwd, signal)))
+                return undefined;
+            const restored = importCaseFromFiles(await readExportFiles(sourceDir, fs, cwd, signal));
+            if (restored.caseId !== caseId)
+                return undefined;
+            const nextCase = decide(recordEvent(restored, 'case_rehydrated', { sourceDir }));
+            cases.set(key, nextCase);
+            return nextCase;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const requireCase = async (key, exec) => {
+        const existing = cases.get(key);
+        if (existing)
+            return existing;
+        const caseId = keyCaseId(key);
+        const fs = fsService();
+        if (fs) {
+            const restored = await rehydrate(caseId, key, fs, execCwd(exec), exec?.signal);
+            if (restored)
+                return restored;
+        }
+        const known = [...cases.keys()]
+            .filter(entry => entry.startsWith(`${String(exec?.agent?.id ?? 'unscoped')}::`))
+            .map(entry => keyCaseId(entry));
+        throw new Error(`Unknown case: ${caseId}. No in-memory case and no restorable export at ${caseExportDir(caseId)}.`
+            + (known.length ? ` Known cases in this session: ${known.join(', ')}.` : '')
+            + ' Use scout_start to create it or scout_import to restore it from a directory.');
     };
+    /* -------------------------------------------------------------- *
+     * Tools
+     * -------------------------------------------------------------- */
     ctx.effect(function* registerScoutTools() {
         yield () => cases.clear();
         yield ctx.tools.register(defineTool({
             name: 'scout_start',
-            description: 'Start a company and job due-diligence case. The initial decision is VERIFY until identity evidence is confirmed.',
+            description: 'Start a company and job due-diligence case. The initial decision is VERIFY until identity evidence is confirmed. Returns a compact status summary; use scout_report for the full report.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Stable case identifier.' },
                 companyName: { type: 'string', required: true, description: 'Company or brand name to investigate.' },
                 roleTitle: { type: 'string', required: true, description: 'Role title to evaluate.' },
                 location: { type: 'string', required: true, description: 'Job location, or an empty string if unknown.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
                 if (cases.has(key))
                     throw new Error(`Case already exists: ${args.caseId}`);
-                const scoutCase = createCase({
+                let nextCase = recordEvent(createCase({
                     caseId: args.caseId,
                     companyName: args.companyName,
                     roleTitle: args.roleTitle,
                     location: args.location || undefined,
-                });
-                let nextCase = recordEvent(scoutCase, 'case_started', {
+                    language,
+                }), 'case_started', {
                     companyName: args.companyName,
                     roleTitle: args.roleTitle,
                     location: args.location || null,
                 });
-                nextCase = await maybePersist(nextCase);
+                const persisted = await maybePersist(nextCase, exec);
+                nextCase = persisted.scoutCase;
                 cases.set(key, nextCase);
-                return JSON.stringify(nextCase, null, 2);
+                return buildEnvelope(nextCase, { kind: 'case_started', ids: [nextCase.caseId] }, { persist: persisted.persist });
             },
         }));
         yield ctx.tools.register(defineTool({
             name: 'scout_add_claim',
-            description: 'Add a sourced or explicitly unverified claim to an active dsh-scout case.',
+            description: 'Add a sourced or explicitly unverified claim to an active dsh-scout case. Returns a compact status summary; use scout_report for the full ledger.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Existing case identifier.' },
                 claimId: { type: 'string', required: true, description: 'Stable claim identifier.' },
@@ -122,14 +451,11 @@ export function apply(ctx, config = {}) {
                 confidenceNote: { type: 'string', required: true, description: 'Why the current evidence supports this status and level.' },
                 nextAction: { type: 'string', required: true, description: 'Smallest next action to verify or use the claim.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                const scoutCase = requireCase(key);
-                let nextCase = recordEvent(decideCase(addClaim(scoutCase, {
+                const scoutCase = await requireCase(key, exec);
+                let nextCase = recordEvent(decide(addClaim(scoutCase, {
                     claimId: args.claimId,
                     text: args.text,
                     status: args.status,
@@ -146,25 +472,23 @@ export function apply(ctx, config = {}) {
                     dimension: args.dimension,
                     impact: args.impact,
                 });
-                nextCase = await maybePersist(nextCase);
+                const persisted = await maybePersist(nextCase, exec);
+                nextCase = persisted.scoutCase;
                 cases.set(key, nextCase);
-                return JSON.stringify(nextCase, null, 2);
+                return buildEnvelope(nextCase, { kind: 'claim_added', ids: [args.claimId] }, { persist: persisted.persist });
             },
         }));
         yield ctx.tools.register(defineTool({
             name: 'scout_ingest',
-            description: 'Batch-register collected research results as sources, optionally drafting claims from each item. itemsJson is a JSON array of { url, title?, sourceType?, evidenceLevel?, claim? }; claim is { text, dimension, impact?, status?, evidenceLevel? } with status defaulting to reported, impact to material, and evidence level to the source level. Source type and evidence level are inferred from the URL when omitted (official registry/regulator origins map to E3, job platforms to job_posting/E2, user-provided to E1, unknown to other/E2). Individual invalid items or rejected claims are reported in errors without aborting the batch; a failed claim does not undo its already-registered source.',
+            description: 'Batch-register collected research results as sources, optionally drafting claims from each item. itemsJson is a JSON array of { url, title?, sourceType?, evidenceLevel?, claim? }; claim is { text, dimension, impact?, status?, evidenceLevel? } with status defaulting to reported, impact to material, and evidence level to the source level. Source type and evidence level are inferred from the URL when omitted (official registry/regulator origins map to E3, job platforms to job_posting/E2, user-provided to E1, unknown to other/E2). A URL already registered for the case is reused instead of duplicated. Individual invalid items or rejected claims are reported in errors without aborting the batch; a failed claim does not undo its already-registered source.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Existing case identifier.' },
                 itemsJson: { type: 'string', required: true, description: 'JSON array of collected source items.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                let scoutCase = requireCase(key);
+                let scoutCase = await requireCase(key, exec);
                 let items;
                 try {
                     const parsed = JSON.parse(args.itemsJson);
@@ -173,10 +497,10 @@ export function apply(ctx, config = {}) {
                     items = parsed;
                 }
                 catch (error) {
-                    throw new Error(`Invalid itemsJson: ${error instanceof Error ? error.message : String(error)}`);
+                    throw new Error(`Invalid itemsJson: ${messageOf(error)}`);
                 }
                 const added = [];
-                const errors = [];
+                const failures = [];
                 let nextId = (scoutCase.sources.length ?? 0) + 1;
                 let nextClaimId = (scoutCase.claims.length ?? 0) + 1;
                 for (const rawItem of items) {
@@ -185,13 +509,13 @@ export function apply(ctx, config = {}) {
                         : String(rawItem?.url ?? rawItem ?? '');
                     try {
                         if (!rawItem || typeof rawItem !== 'object') {
-                            errors.push({ url: String(rawItem ?? ''), error: 'item must be an object' });
+                            failures.push({ url: String(rawItem ?? ''), error: 'item must be an object' });
                             continue;
                         }
                         const item = rawItem;
                         const url = typeof item.url === 'string' ? item.url.trim() : '';
                         if (!url) {
-                            errors.push({ url: String(item.url ?? ''), error: 'url is required' });
+                            failures.push({ url: String(item.url ?? ''), error: 'url is required' });
                             continue;
                         }
                         const explicitType = typeof item.sourceType === 'string' && SOURCE_TYPES.includes(item.sourceType)
@@ -201,44 +525,43 @@ export function apply(ctx, config = {}) {
                             ? item.evidenceLevel
                             : undefined;
                         if (item.sourceType !== undefined && item.sourceType !== null && !explicitType) {
-                            errors.push({ url, error: `invalid sourceType: ${String(item.sourceType)}` });
+                            failures.push({ url, error: `invalid sourceType: ${String(item.sourceType)}` });
                             continue;
                         }
                         if (item.evidenceLevel !== undefined && item.evidenceLevel !== null && !explicitLevel) {
-                            errors.push({ url, error: `invalid evidenceLevel: ${String(item.evidenceLevel)}` });
+                            failures.push({ url, error: `invalid evidenceLevel: ${String(item.evidenceLevel)}` });
                             continue;
                         }
                         const typeGuess = inferSourceType(url, explicitType, authoritySuffixes);
                         const levelGuess = inferEvidenceLevel(url, typeGuess.type, explicitLevel, authoritySuffixes);
-                        let sourceId = `src-${nextId}`;
-                        while (scoutCase.sources.some(source => source.sourceId === sourceId)) {
+                        const existing = findSourceByUrl(scoutCase, url);
+                        let source;
+                        if (existing) {
+                            source = existing;
+                        }
+                        else {
+                            let sourceId = `src-${nextId}`;
+                            while (scoutCase.sources.some(candidate => candidate.sourceId === sourceId)) {
+                                nextId += 1;
+                                sourceId = `src-${nextId}`;
+                            }
                             nextId += 1;
-                            sourceId = `src-${nextId}`;
+                            source = {
+                                sourceId,
+                                type: typeGuess.type,
+                                title: typeof item.title === 'string' && item.title.trim() ? item.title.trim() : url,
+                                url,
+                                capturedAt: new Date().toISOString(),
+                                evidenceLevel: levelGuess.evidenceLevel,
+                                status: 'captured',
+                            };
+                            scoutCase = registerSource(scoutCase, source);
                         }
-                        nextId += 1;
-                        const title = typeof item.title === 'string' && item.title.trim() ? item.title.trim() : url;
-                        const source = {
-                            sourceId,
-                            type: typeGuess.type,
-                            title,
-                            url,
-                            capturedAt: new Date().toISOString(),
-                            evidenceLevel: levelGuess.evidenceLevel,
-                            status: 'captured',
-                        };
-                        scoutCase = registerSource(scoutCase, source);
-                        const addedEntry = {
-                            sourceId,
-                            title,
-                            url,
-                            type: typeGuess.type,
-                            evidenceLevel: levelGuess.evidenceLevel,
-                            inferred: { type: typeGuess.inferred, evidenceLevel: levelGuess.inferred },
-                        };
+                        added.push(source.sourceId);
                         const rawClaim = item.claim;
                         if (rawClaim !== undefined && rawClaim !== null) {
                             if (typeof rawClaim !== 'object') {
-                                errors.push({ url, error: 'claim must be an object' });
+                                failures.push({ url, error: 'claim must be an object' });
                             }
                             else {
                                 const claimDraft = rawClaim;
@@ -270,11 +593,11 @@ export function apply(ctx, config = {}) {
                                 if (!dimension)
                                     claimIssues.push(`invalid claim.dimension: ${String(claimDraft.dimension)}`);
                                 if (claimIssues.length) {
-                                    errors.push({ url, error: `claim rejected: ${claimIssues.join('; ')}` });
+                                    failures.push({ url, error: `claim rejected: ${claimIssues.join('; ')}` });
                                 }
                                 else {
                                     let claimId = `claim-${nextClaimId}`;
-                                    while (scoutCase.claims.some(claim => claim.claimId === claimId)) {
+                                    while (scoutCase.claims.some(candidate => candidate.claimId === claimId)) {
                                         nextClaimId += 1;
                                         claimId = `claim-${nextClaimId}`;
                                     }
@@ -288,8 +611,8 @@ export function apply(ctx, config = {}) {
                                             dimension: dimension,
                                             impact: impact ?? 'material',
                                             sourceIds: [source.sourceId],
-                                            confidenceNote: `由采集项自动登记，来源 ${source.sourceId}`,
-                                            nextAction: '核验该主张并补充独立来源',
+                                            confidenceNote: formatScoutString(strings.ingest.autoConfidenceNote, { sourceId: source.sourceId }),
+                                            nextAction: strings.ingest.autoNextAction,
                                         }), 'claim_added', {
                                             claimId,
                                             status: status ?? 'reported',
@@ -300,107 +623,95 @@ export function apply(ctx, config = {}) {
                                             sourceIds: [source.sourceId],
                                             ingested: true,
                                         });
-                                        addedEntry.claims = [claimId];
+                                        added.push(claimId);
                                     }
                                     catch (error) {
-                                        errors.push({ url, error: `claim rejected: ${error instanceof Error ? error.message : String(error)}` });
+                                        failures.push({ url, error: `claim rejected: ${messageOf(error)}` });
                                     }
                                 }
                             }
                         }
-                        added.push(addedEntry);
                     }
                     catch (error) {
-                        errors.push({ url: itemUrl(), error: error instanceof Error ? error.message : String(error) });
+                        failures.push({ url: itemUrl(), error: messageOf(error) });
                     }
                 }
-                scoutCase = decideCase(scoutCase);
-                scoutCase = await maybePersist(scoutCase);
+                scoutCase = decide(scoutCase);
+                const persisted = await maybePersist(scoutCase, exec);
+                scoutCase = persisted.scoutCase;
                 cases.set(key, scoutCase);
-                return JSON.stringify({ added, errors }, null, 2);
+                return buildEnvelope(scoutCase, { kind: 'sources_added', ids: added }, { persist: persisted.persist, errors: failures });
             },
         }));
         yield ctx.tools.register(defineTool({
             name: 'scout_search',
-            description: 'Run a web search through the DSH web provider and auto-register the result URLs as sources for the case (type and evidence level inferred per URL). Optionally limits how many results are registered.',
+            description: 'Run a web search through the DSH web provider and auto-register the result URLs as sources for the case (type and evidence level inferred per URL; a URL already registered for the case is reused). Optionally limits how many results are registered.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Existing case identifier.' },
                 query: { type: 'string', required: true, description: 'Search query to run through the web provider.' },
                 limit: { type: 'number', description: 'Maximum number of search results to register (default 5, capped at 10).' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
+                const web = webService();
                 if (!web)
                     throw new Error('Web search service is unavailable in this host');
                 const key = caseKey(args.caseId, exec.agent?.id);
-                let scoutCase = requireCase(key);
+                let scoutCase = await requireCase(key, exec);
                 const parsedLimit = Math.trunc(args.limit ?? 5);
                 const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, 10) : 5;
                 const result = await web.search({ query: args.query, maxResults: limit }, exec.signal);
                 const added = [];
-                const errors = [];
+                const failures = [];
                 const items = Array.isArray(result.sources) ? result.sources : [];
                 if (!Array.isArray(result.sources)) {
-                    errors.push({ url: '', error: 'search provider returned a non-array sources field' });
+                    failures.push({ url: '', error: 'search provider returned a non-array sources field' });
                 }
                 let nextId = (scoutCase.sources.length ?? 0) + 1;
                 items.forEach((item, index) => {
                     if (!item || typeof item !== 'object') {
-                        errors.push({ url: '', error: `search result ${index} must be an object` });
+                        failures.push({ url: '', error: `search result ${index} must be an object` });
                         return;
                     }
                     const url = typeof item.url === 'string' ? item.url.trim() : '';
                     if (!url) {
-                        errors.push({ url: '', error: `search result ${index} missing url` });
+                        failures.push({ url: '', error: `search result ${index} missing url` });
                         return;
                     }
                     try {
+                        const existing = findSourceByUrl(scoutCase, url);
+                        if (existing) {
+                            added.push(existing.sourceId);
+                            return;
+                        }
                         const typeGuess = inferSourceType(url, undefined, authoritySuffixes);
                         const levelGuess = inferEvidenceLevel(url, typeGuess.type, undefined, authoritySuffixes);
                         let sourceId = `src-${nextId}`;
-                        while (scoutCase.sources.some(source => source.sourceId === sourceId)) {
+                        while (scoutCase.sources.some(candidate => candidate.sourceId === sourceId)) {
                             nextId += 1;
                             sourceId = `src-${nextId}`;
                         }
                         nextId += 1;
-                        const title = typeof item.title === 'string' && item.title.trim() ? item.title.trim() : url;
                         scoutCase = registerSource(scoutCase, {
                             sourceId,
                             type: typeGuess.type,
-                            title,
+                            title: typeof item.title === 'string' && item.title.trim() ? item.title.trim() : url,
                             url,
                             capturedAt: new Date().toISOString(),
                             evidenceLevel: levelGuess.evidenceLevel,
                             status: 'captured',
                         });
-                        added.push({
-                            sourceId,
-                            title,
-                            url,
-                            type: typeGuess.type,
-                            evidenceLevel: levelGuess.evidenceLevel,
-                            snippet: typeof item.snippet === 'string' ? item.snippet.slice(0, 300) : null,
-                            publishedAt: typeof item.publishedAt === 'string' ? item.publishedAt : null,
-                            inferred: { type: typeGuess.inferred, evidenceLevel: levelGuess.inferred },
-                        });
+                        added.push(sourceId);
                     }
                     catch (error) {
-                        errors.push({ url, error: error instanceof Error ? error.message : String(error) });
+                        failures.push({ url, error: messageOf(error) });
                     }
                 });
-                scoutCase = decideCase(scoutCase);
-                scoutCase = await maybePersist(scoutCase);
+                scoutCase = decide(scoutCase);
+                const persisted = await maybePersist(scoutCase, exec);
+                scoutCase = persisted.scoutCase;
                 cases.set(key, scoutCase);
-                return JSON.stringify({
-                    query: args.query,
-                    truncated: Boolean(result.truncated),
-                    added,
-                    errors,
-                    content: typeof result.content === 'string' && result.content ? result.content.slice(0, 500) : null,
-                }, null, 2);
+                return buildEnvelope(scoutCase, { kind: 'sources_added', ids: added }, { persist: persisted.persist, errors: failures });
             },
         }));
         yield ctx.tools.register(defineTool({
@@ -410,8 +721,21 @@ export function apply(ctx, config = {}) {
                 caseIds: { type: 'string', required: true, description: 'Comma-separated case identifiers; at least two, at most five.' },
             },
             output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        caseIds: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            required: true,
+                        },
+                        report: { type: 'string', required: true },
+                    },
+                },
+                render: (_args, value) => [
+                    { type: 'text', text: value.report },
+                ],
             },
             async execute(args, exec) {
                 const agentId = exec.agent?.id;
@@ -421,60 +745,112 @@ export function apply(ctx, config = {}) {
                 const caseIds = [...new Set(rawIds)];
                 if (caseIds.length < 2)
                     throw new Error('Comparison requires at least two distinct case ids');
-                const compared = caseIds.map(caseId => {
-                    try {
-                        return requireCase(caseKey(caseId, agentId));
-                    }
-                    catch (error) {
-                        throw new Error(`Unknown case: ${caseId} (not found in this agent session)`);
-                    }
-                });
-                return renderComparison(compared);
+                const compared = [];
+                for (const caseId of caseIds) {
+                    compared.push(await requireCase(caseKey(caseId, agentId), exec));
+                }
+                return { caseIds, report: renderComparison(compared, { language }) };
             },
         }));
         yield ctx.tools.register(defineTool({
             name: 'scout_report',
-            description: 'Render the current evidence-bounded report for a dsh-scout case.',
+            description: 'Render the full evidence-bounded report for a dsh-scout case. This is the only tool that returns the complete artifact; mutation tools return compact summaries.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Existing case identifier.' },
             },
             output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        caseId: { type: 'string', required: true },
+                        decision: {
+                            type: 'string',
+                            enum: ['PROCEED', 'VERIFY', 'STOP'],
+                            required: true,
+                        },
+                        report: { type: 'string', required: true },
+                        coverage: {
+                            type: 'array',
+                            required: true,
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    dimension: {
+                                        type: 'string',
+                                        enum: [...CLAIM_DIMENSIONS],
+                                        required: true,
+                                    },
+                                    verified: { type: 'integer', required: true },
+                                    open: { type: 'integer', required: true },
+                                    untouched: { type: 'boolean', required: true },
+                                },
+                            },
+                        },
+                    },
+                },
+                render: (_args, value) => [
+                    { type: 'text', text: value.report },
+                ],
             },
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                return renderReport(requireCase(key));
+                const scoutCase = await requireCase(key, exec);
+                return {
+                    caseId: scoutCase.caseId,
+                    decision: scoutCase.decision,
+                    report: renderReportOf(scoutCase),
+                    coverage: computeCoverage(scoutCase),
+                };
             },
         }));
         yield ctx.tools.register(defineTool({
             name: 'scout_export',
-            description: 'Persist a dsh-scout case as the durable five-file export (case.json, sources.json, claims.json, events.jsonl, report.md). targetDir is optional and defaults to the configured scoutDir (or ./dsh-scout) plus the case id.',
+            description: 'Persist a dsh-scout case as the durable five-file export (case.json, sources.json, claims.json, events.jsonl, report.md) plus a completion marker. targetDir is optional and defaults to the configured scoutDir (or ./dsh-scout) plus the case id. The returned targetDir is the resolved absolute directory.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Existing case identifier.' },
                 targetDir: { type: 'string', description: 'Directory path to write the five export files into; defaults to <scoutDir>/<caseId>.' },
             },
             output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        caseId: { type: 'string', required: true },
+                        targetDir: { type: 'string', required: true },
+                        files: { type: 'array', items: { type: 'string' }, required: true },
+                        persisted: { type: 'boolean', required: true },
+                        complete: { type: 'boolean', required: true },
+                        error: { type: 'string' },
+                    },
+                },
+                render: (_args, value) => [
+                    {
+                        type: 'text',
+                        text: value.persisted
+                            ? `exported to ${value.targetDir} (complete: ${value.complete})`
+                            : `EXPORT FAILED (${value.targetDir}): ${value.error ?? 'unknown error'}`,
+                    },
+                ],
             },
             async execute(args, exec) {
+                const fs = fsService();
+                if (!fs)
+                    throw new Error('Filesystem service is unavailable in this host');
                 const key = caseKey(args.caseId, exec.agent?.id);
-                const scoutCase = requireCase(key);
+                const scoutCase = await requireCase(key, exec);
                 const targetDir = args.targetDir || caseExportDir(scoutCase.caseId);
-                const result = await persistFiles(scoutCase, targetDir);
-                let nextCase = scoutCase;
-                if (result.persisted) {
-                    nextCase = recordEvent(scoutCase, 'case_exported', { targetDir: result.targetDir });
-                    cases.set(key, nextCase);
-                }
-                return JSON.stringify({
-                    caseId: args.caseId,
-                    targetDir: result.targetDir,
-                    files: EXPORT_FILE_NAMES,
-                    persisted: result.persisted,
-                    ...(result.error ? { error: result.error } : {}),
-                }, null, 2);
+                const exported = await exportCase(scoutCase, targetDir, fs, execCwd(exec), exec.signal, false);
+                cases.set(key, exported.scoutCase);
+                return {
+                    caseId: scoutCase.caseId,
+                    targetDir: exported.persist.targetDir,
+                    files: [...EXPORT_FILE_NAMES, EXPORT_MARKER_FILE],
+                    persisted: exported.persist.persisted,
+                    complete: exported.persist.persisted,
+                    ...(exported.persist.error ? { error: exported.persist.error } : {}),
+                };
             },
         }));
         yield ctx.tools.register(defineTool({
@@ -484,44 +860,54 @@ export function apply(ctx, config = {}) {
                 caseId: { type: 'string', required: true, description: 'Existing case identifier.' },
             },
             output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        caseId: { type: 'string', required: true },
+                        questions: { type: 'array', items: { type: 'string' }, required: true },
+                    },
+                },
+                render: (_args, value) => [
+                    {
+                        type: 'text',
+                        text: value.questions.length
+                            ? value.questions.map((question, index) => `${index + 1}. ${question}`).join('\n')
+                            : 'No interview questions derived yet.',
+                    },
+                ],
             },
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                return JSON.stringify(generateInterviewQuestions(requireCase(key)), null, 2);
+                const scoutCase = await requireCase(key, exec);
+                return { caseId: scoutCase.caseId, questions: generateInterviewQuestions(scoutCase, { language }) };
             },
         }));
         yield ctx.tools.register(defineTool({
             name: 'scout_import',
-            description: 'Restore a dsh-scout case from a five-file export directory, then recompute its decision.',
+            description: 'Restore a dsh-scout case from a five-file export directory, then recompute its decision. Exports written before 0.9.1 have no completion marker: they still import, but `complete` reports false.',
             parameters: {
                 caseId: { type: 'string', required: true, description: 'Case identifier to restore; must match the exported case.json.' },
                 sourceDir: { type: 'string', required: true, description: 'Directory path containing the five export files.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
+                const fs = fsService();
                 if (!fs)
                     throw new Error('Filesystem service is unavailable in this host');
                 const key = caseKey(args.caseId, exec.agent?.id);
-                const read = async (name) => {
-                    const target = await fs.resolve(`${args.sourceDir}/${name}`);
-                    return fs.readText(target);
-                };
-                const files = {};
-                for (const name of ['case.json', 'sources.json', 'claims.json', 'events.jsonl']) {
-                    files[name] = await read(name);
-                }
-                const restored = importCaseFromFiles(files);
+                const cwd = execCwd(exec);
+                const restored = importCaseFromFiles(await readExportFiles(args.sourceDir, fs, cwd, exec.signal));
                 if (restored.caseId !== args.caseId) {
                     throw new Error(`Case id mismatch: export has ${restored.caseId}, requested ${args.caseId}`);
                 }
-                const nextCase = decideCase(recordEvent(restored, 'case_imported', { sourceDir: args.sourceDir }));
+                const nextCase = decide(recordEvent(restored, 'case_imported', { sourceDir: args.sourceDir }));
                 cases.set(key, nextCase);
-                return JSON.stringify(nextCase, null, 2);
+                return {
+                    ...buildEnvelope(nextCase, { kind: 'case_imported', ids: [nextCase.caseId] }),
+                    sourceDir: args.sourceDir,
+                    complete: await readCompletionMarker(args.sourceDir, fs, cwd, exec.signal),
+                };
             },
         }));
         yield ctx.tools.register(defineTool({
@@ -535,13 +921,10 @@ export function apply(ctx, config = {}) {
                 url: { type: 'string', required: true, description: 'Source URL, or an empty string for local/user-provided material.' },
                 evidenceLevel: { type: 'string', enum: EVIDENCE_LEVELS, required: true, description: 'Source quality from E0 to E3.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                const scoutCase = requireCase(key);
+                const scoutCase = await requireCase(key, exec);
                 const source = {
                     sourceId: args.sourceId,
                     type: args.sourceType,
@@ -555,9 +938,10 @@ export function apply(ctx, config = {}) {
                     sourceId: source.sourceId,
                     evidenceLevel: source.evidenceLevel,
                 });
-                nextCase = await maybePersist(nextCase);
+                const persisted = await maybePersist(nextCase, exec);
+                nextCase = persisted.scoutCase;
                 cases.set(key, nextCase);
-                return JSON.stringify(nextCase, null, 2);
+                return buildEnvelope(nextCase, { kind: 'source_added', ids: [args.sourceId] }, { persist: persisted.persist });
             },
         }));
         yield ctx.tools.register(defineTool({
@@ -572,14 +956,11 @@ export function apply(ctx, config = {}) {
                 brandRelationship: { type: 'string', required: true, description: 'How the investigated brand relates to the legal entity.' },
                 sourceIds: { type: 'string', required: true, description: 'Comma-separated identity sources including a linked authoritative E3 source.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                const scoutCase = requireCase(key);
-                let nextCase = recordEvent(decideCase(verifyIdentity(scoutCase, {
+                const scoutCase = await requireCase(key, exec);
+                let nextCase = recordEvent(decide(verifyIdentity(scoutCase, {
                     legalEntity: args.legalEntity,
                     registrationNumber: args.registrationNumber,
                     registeredRegion: args.registeredRegion,
@@ -590,9 +971,10 @@ export function apply(ctx, config = {}) {
                     legalEntity: args.legalEntity,
                     registrationNumber: args.registrationNumber,
                 });
-                nextCase = await maybePersist(nextCase);
+                const persisted = await maybePersist(nextCase, exec);
+                nextCase = persisted.scoutCase;
                 cases.set(key, nextCase);
-                return JSON.stringify(nextCase, null, 2);
+                return buildEnvelope(nextCase, { kind: 'identity_verified', ids: [args.legalEntity] }, { persist: persisted.persist });
             },
         }));
         yield ctx.tools.register(defineTool({
@@ -606,14 +988,11 @@ export function apply(ctx, config = {}) {
                 confidenceNote: { type: 'string', required: true, description: 'Why the new sources justify verified status.' },
                 nextAction: { type: 'string', required: true, description: 'Smallest next action after verification.' },
             },
-            output: {
-                schema: { type: 'string' },
-                render: (_args, value) => [{ type: 'text', text: value }],
-            },
+            output: mutationOutput(),
             async execute(args, exec) {
                 const key = caseKey(args.caseId, exec.agent?.id);
-                const scoutCase = requireCase(key);
-                let nextCase = recordEvent(decideCase(verifyClaim(scoutCase, {
+                const scoutCase = await requireCase(key, exec);
+                let nextCase = recordEvent(decide(verifyClaim(scoutCase, {
                     claimId: args.claimId,
                     evidenceLevel: args.evidenceLevel,
                     sourceIds: args.sourceIds.split(',').map(value => value.trim()).filter(Boolean),
@@ -623,11 +1002,108 @@ export function apply(ctx, config = {}) {
                     claimId: args.claimId,
                     evidenceLevel: args.evidenceLevel,
                 });
-                nextCase = await maybePersist(nextCase);
+                const persisted = await maybePersist(nextCase, exec);
+                nextCase = persisted.scoutCase;
                 cases.set(key, nextCase);
-                return JSON.stringify(nextCase, null, 2);
+                return buildEnvelope(nextCase, { kind: 'claim_verified', ids: [args.claimId] }, { persist: persisted.persist });
             },
         }));
     }, 'dsh-scout tools');
+    /* -------------------------------------------------------------- *
+     * Host entry points: a `/scout` command and a registered Skill.
+     * Both are optional services bound through `ctx.inject`, so a host
+     * without them simply skips the registration.
+     * -------------------------------------------------------------- */
+    const runScoutCommand = async (invocation) => {
+        const raw = typeof invocation?.rawInput === 'string' ? invocation.rawInput.trim() : '';
+        const [action = 'help', caseId = ''] = raw.split(/\s+/).filter(Boolean);
+        if (action === 'help' || !caseId) {
+            return {
+                kind: 'success',
+                text: 'usage: /scout status <caseId> | /scout questions <caseId> | /scout report <caseId> | /scout export <caseId> [targetDir]',
+            };
+        }
+        const key = caseKey(caseId, invocation?.agent?.id);
+        const scoutCase = cases.get(key);
+        if (!scoutCase) {
+            return { kind: 'error', text: `Unknown case: ${caseId}. Use scout_start or scout_import first.` };
+        }
+        if (action === 'status') {
+            const verified = scoutCase.claims.filter(claim => claim.status === 'verified').length;
+            return {
+                kind: 'success',
+                text: `[${scoutCase.caseId}] ${scoutCase.decision} · identity ${scoutCase.subject.identityStatus}`
+                    + ` · sources ${scoutCase.sources.length} / claims ${scoutCase.claims.length}`
+                    + ` (verified ${verified}, open ${scoutCase.claims.length - verified})`,
+            };
+        }
+        if (action === 'questions') {
+            return { kind: 'success', text: generateInterviewQuestions(scoutCase, { language }).map((q, i) => `${i + 1}. ${q}`).join('\n') };
+        }
+        if (action === 'report') {
+            return { kind: 'success', text: renderReportOf(scoutCase) };
+        }
+        if (action === 'export') {
+            const fs = fsService();
+            if (!fs)
+                return { kind: 'error', text: 'Filesystem service is unavailable in this host' };
+            const targetDir = caseExportDir(scoutCase.caseId);
+            const exported = await exportCase(scoutCase, targetDir, fs, invocation?.agent?.session?.header?.cwd, invocation?.signal, false);
+            cases.set(key, exported.scoutCase);
+            return exported.persist.persisted
+                ? { kind: 'success', text: `exported to ${exported.persist.targetDir}` }
+                : { kind: 'error', text: `export failed (${exported.persist.targetDir}): ${exported.persist.error ?? 'unknown error'}` };
+        }
+        return { kind: 'error', text: `Unknown /scout action: ${action}` };
+    };
+    const SCOUT_SKILL_CONTENT = [
+        '# dsh-scout (司察) due-diligence workflow',
+        '',
+        'Use the scout tools when the user wants to judge whether a company and a role are worth',
+        'pursuing, and what must be verified before deciding.',
+        '',
+        '## Order',
+        '1. `scout_start` — create the case. The decision starts at VERIFY.',
+        '2. `scout_search` / `scout_ingest` / `scout_add_source` — collect and register sources.',
+        '3. `scout_add_claim` — attach evidence-bounded claims (batch drafts come from `scout_ingest`).',
+        '4. `scout_verify_identity` — confirm the legal entity from an E3 registry/regulator source.',
+        '5. `scout_verify_claim` — promote a claim once stronger sources exist.',
+        '6. `scout_report` / `scout_questions` — the full report and the interview question list.',
+        '7. `scout_export` — persist the five-file export; `scout_import` restores it later.',
+        '',
+        '## Evidence discipline (enforced by the tools, do not try to bypass)',
+        '1. A claim may never cite a higher evidence level than its strongest source.',
+        '2. A high-impact claim with no source must stay `unknown` or `needs_verification`.',
+        '3. `scout_verify_identity` requires a linked E3 registry/regulator/official-filing source over HTTPS.',
+        '4. The decision stays VERIFY while the identity is unverified or a blocking/material claim is open.',
+        '',
+        '## Reading tool output',
+        'Mutation tools return a compact status summary (decision, counts, what changed, next actions).',
+        'Call `scout_report` when the full ledger is actually needed instead of re-reading every mutation.',
+    ].join('\n');
+    const bindOptional = (serviceName, install) => {
+        ctx.inject([serviceName], (child) => {
+            const service = child[serviceName];
+            if (!service)
+                return;
+            child.effect(() => install(service), `dsh-scout ${serviceName}`);
+        });
+    };
+    bindOptional('commands', service => service.register({
+        name: 'scout',
+        description: 'Inspect a dsh-scout case: /scout status|questions|report|export <caseId>',
+        handler: runScoutCommand,
+    }));
+    bindOptional('skills', service => service.register({
+        name: 'scout',
+        description: 'Evidence-driven company and job due diligence with the dsh-scout tools.',
+        whenToUse: 'When the user asks whether a company/role is worth pursuing, or wants a background check with sources and interview questions.',
+        content: SCOUT_SKILL_CONTENT,
+        // `SkillRegistration` keeps `source` required (only invocation/provider are
+        // optional); the registry defaults provider but never source, so omitting it
+        // yields a summary whose declared non-optional `source` reads back undefined.
+        source: 'runtime',
+        invocation: { modelInvocable: true, userInvocable: true },
+    }));
 }
 export * from './model.js';