@12ui/design 0.2.55 → 0.2.57

package/dist/improve-run-summary.js

@@ -0,0 +1,180 @@
+import path from 'node:path';
+import { formatDuration } from './cli-progress.js';
+import { readImproveKitAssets } from './improve-kit-assets.js';
+import { IMPROVE_NO_APPROXIMATION_RULE, improvePickSlotHint, improveRecoveryLine, improveStageStatusLine, readImproveKitStatus, shellArg, } from './improve-kit-status.js';
+import { improveCapturedUrlLine } from './improve-capture-redirect.js';
+import { improveKitIgnoreNote } from './improve-kit-ignore.js';
+import { improveAbandonedLines } from './improve-reset.js';
+import { improvePaths } from './improve-workspace.js';
+/**
+ * The last thing `12ui improve` prints.
+ *
+ * A run that ends with a 200-line JSON record tells a reader nothing about
+ * whether it worked. This block does: stage statuses, what the target actually
+ * is, which raster layers have to be carried by name, the plan result, and the
+ * kit path. On a stall it leads with INCOMPLETE and the recovery commands,
+ * because that is the moment a lane decides whether to code from a PNG.
+ */
+const planLine = (record, status) => {
+    if (status.gateBlocked)
+        return 'Plan: blocked by the coverage gate — read plan/GATE.md';
+    if (!record.plan)
+        return 'Plan: none';
+    return `Plan: ${record.plan.mode}, coverage gate ${record.plan.gate}`;
+};
+/**
+ * The headline is the one line a skimming reader takes away, so it carries the
+ * caveat rather than leaving it eight lines down. A fixed-layout fallback that
+ * announces itself as "Kit ready" is the same defect as `12ui next` reporting
+ * ok over a wedged export.
+ */
+const headline = (record, status) => {
+    if (status.gateBlocked)
+        return 'Kit ready — coverage gate blocked the plan';
+    // "Fixed-layout fallback" named the OUTCOME and not the event, so a reader
+    // who had watched a silent wait could not tell the run had overrun anything
+    // (F8). Name what happened first: the plan is real, and it was built from a
+    // derivation because the responsive export did not settle.
+    if (record.convert?.layout === 'fixed') {
+        return 'Kit ready — responsive export stalled; plan from fixed-layout fallback';
+    }
+    return 'Kit ready';
+};
+/** What stalled and where it is written down, on the line after the headline. */
+const fallbackLines = (record) => {
+    if (record.convert?.layout !== 'fixed')
+        return [];
+    const stall = record.convert.responsiveStall;
+    const id = stall?.conversionId ?? record.convert.sourceConversionId;
+    return [
+        `- Responsive export: stalled${stall
+            ? ` after ${formatDuration(stall.waitedSeconds)} (bound ${formatDuration(stall.boundSeconds)})`
+            : ''}${id ? `, conversion ${id}` : ''}`
+            + ' — read plan/STALL.md, which has the command that collects it later',
+    ];
+};
+const assetsLine = (index) => {
+    if (index.assets.length === 0)
+        return 'Assets: none';
+    const carry = index.rasterLayers
+        .map((layer) => `${layer.kind}${layer.asset ? ` (${layer.asset.id})` : ''}`);
+    return `Assets: ${index.assets.length} file${index.assets.length === 1 ? '' : 's'};`
+        + ` raster layers to carry: ${carry.length > 0 ? carry.join(', ') : 'none declared'}`;
+};
+/**
+ * The kit is inside the repository and committable. One line, at the end, where
+ * the reader is already looking — the run never edits a `.gitignore` it cannot
+ * be sure about, so this is all it can honestly do (F17).
+ */
+const kitIgnoreLines = (record) => {
+    const note = improveKitIgnoreNote(record.kitIgnore);
+    return note ? [`- ${note}`] : [];
+};
+/**
+ * What a run prints when the draw is ready and nobody has chosen.
+ *
+ * This is the whole point of the dispatch-discipline change, so it has to leave
+ * the reader with two things and nothing else: where the candidates are, and
+ * the one command that continues from here. It is a finished run, not a
+ * failure — the stages that were asked for and could run, ran.
+ */
+export const awaitingImprovePick = (args) => {
+    const slots = (args.record.draft?.candidates ?? []).map((candidate) => candidate.slot);
+    return [
+        '',
+        'Draw ready — choose a candidate',
+        `- Candidates: ${slots.length > 0 ? slots.join(', ') : 'none recorded'}`
+            + ` in ${args.options.paths.candidatesDir}`,
+        '- Nothing was converted. A conversion of a candidate nobody chose is money spent on a guess,'
+            + ' and it cannot be cancelled once it starts.',
+        `- Kit: ${args.record.runDir}`,
+        ...kitIgnoreLines(args.record),
+        `Next: 12ui improve ${shellArg(args.record.input.value)}`
+            + ` --out-dir ${shellArg(args.record.runDir)}`
+            + ` --from pick --pick ${improvePickSlotHint(args.record)}`,
+    ].join('\n');
+};
+/**
+ * The page that was photographed, when it is not the page that was requested.
+ * One line, high in the summary, is what the notion app surface needed and did
+ * not get (F27).
+ */
+const capturedLines = (record) => {
+    const line = improveCapturedUrlLine(record);
+    return line ? [`- ${line}`] : [];
+};
+/** Which candidate the target came from, and why that one was converted. */
+const convertedLine = (record) => {
+    if (record.target)
+        return ['- Converted: the supplied --target'];
+    if (!record.pick)
+        return [];
+    return [`- Converted: candidate ${record.pick.slot}, chosen with --pick`];
+};
+export const renderImproveRunSummary = (args) => {
+    const readme = path.join(args.record.runDir, 'README.md');
+    const stages = `Stages: ${args.status.stages.map(improveStageStatusLine).join('; ')}`;
+    if (args.status.complete) {
+        return [
+            '',
+            headline(args.record, args.status),
+            `- ${stages}`,
+            ...capturedLines(args.record),
+            `- Target: ${args.status.targetMode}`,
+            ...fallbackLines(args.record),
+            `- ${assetsLine(args.index)}`,
+            ...convertedLine(args.record),
+            `- ${planLine(args.record, args.status)}`,
+            ...improveAbandonedLines(args.record),
+            `- Kit: ${args.record.runDir}`,
+            ...kitIgnoreLines(args.record),
+            `Next: read ${readme}`,
+        ].join('\n');
+    }
+    return [
+        '',
+        'INCOMPLETE',
+        `- Missing: ${args.status.missing.join(', ')}`,
+        `- ${stages}`,
+        ...capturedLines(args.record),
+        `- Target: ${args.status.targetMode}`,
+        ...fallbackLines(args.record),
+        `- ${assetsLine(args.index)}`,
+        ...convertedLine(args.record),
+        `- ${planLine(args.record, args.status)}`,
+        ...improveAbandonedLines(args.record),
+        `- Kit: ${args.record.runDir}`,
+        ...kitIgnoreLines(args.record),
+        '- Recovery:',
+        ...args.status.recovery.map(improveRecoveryLine),
+        `- ${IMPROVE_NO_APPROXIMATION_RULE}`,
+        `Next: read ${readme}`,
+    ].join('\n');
+};
+export const buildImproveRunSummary = async (args) => {
+    const paths = improvePaths(args.record.runDir);
+    const [status, index] = await Promise.all([
+        readImproveKitStatus({
+            record: args.record,
+            ...(args.requestedTo ? { requestedTo: args.requestedTo } : {}),
+        }),
+        readImproveKitAssets({ runDir: args.record.runDir, layerDocPath: paths.targetLayerDoc }),
+    ]);
+    return renderImproveRunSummary({ record: args.record, status, index });
+};
+/**
+ * Put the summary AFTER the failure text.
+ *
+ * `cli.ts` prints `error.message` last, so a summary written to stdout before
+ * the throw leaves the reader's final line as the error rather than
+ * "Next: read <kit>/README.md" — which is the line the summary exists to
+ * leave there. Carrying it in the message is what keeps the order right.
+ */
+export const improveStallErrorWithSummary = (error, summary) => {
+    if (error instanceof Error) {
+        error.message = `${error.message}\n${summary}`;
+        return error;
+    }
+    return new Error(`${String(error)}\n${summary}`);
+};
+//# sourceMappingURL=improve-run-summary.js.map

package/dist/improve-run-summary.js.map

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

package/dist/improve-stage-shared.d.ts

@@ -1,8 +1,9 @@
 import { runConversionCommand } from './cli-convert-command.js';
 import { runDraftCommand } from './cli-draft-command.js';
 import { captureImprovePage } from './redesign-capture.js';
+import type { ImproveStopTarget } from './improve-stop-handler.js';
 import type { RunJournalNotes } from './run-journal.js';
-import { type ImproveRecord, type ImproveStage } from './improve-workspace.js';
+import { type ImproveRecord, type ImproveStage, type ImproveStageOutcome } from './improve-workspace.js';
 export type ImproveCommandDependencies = {
     capture?: typeof captureImprovePage;
     runDraft?: typeof runDraftCommand;
@@ -13,8 +14,21 @@ export type ImproveCommandDependencies = {
     sleep?: (milliseconds: number) => Promise<void>;
     onRunDirectory?: (runDir: string) => void;
     journal?: RunJournalNotes;
+    /** Where the stop handler listens; `process` unless a test supplies one. */
+    stopTarget?: ImproveStopTarget;
+    /** How a stopped run leaves; `process.exit` unless a test supplies one. */
+    exit?: (code: number) => void;
 };
 export declare const improveSha256: (bytes: Uint8Array) => string;
+/**
+ * The word for what this stage did, read off the record it just wrote (F28).
+ *
+ * The facts were always there — `convert.layout`, `convert.responsiveWarning`,
+ * `plan.gate` — and the README already printed them. Only `improve.json` said
+ * `settled` over a fixed-layout fallback and a gate-blocked plan, which is the
+ * one place a supervisor or a campaign parser looks.
+ */
+export declare const improveStageOutcome: (record: ImproveRecord, stage: ImproveStage) => ImproveStageOutcome;
 export declare const noteImproveStage: (args: {
     record: ImproveRecord;
     stage: ImproveStage;
@@ -23,5 +37,34 @@ export declare const noteImproveStage: (args: {
     outcome?: "settled" | "skipped";
     write: boolean;
 }) => Promise<ImproveRecord>;
+/**
+ * The paid call this stage dispatched did not come back in this run.
+ *
+ * It rewrites the dispatched entry rather than adding one, so the price stays
+ * the price of the call that is still running and a resume still re-attaches
+ * to it. A stage with no entry bought nothing; it gets an unpriced `stalled`
+ * entry only when the run itself stalled, so `stages.plan.outcome` can say so
+ * instead of staying silent.
+ */
+export declare const markImproveStageStalled: (args: {
+    record: ImproveRecord;
+    stage: ImproveStage;
+    stalled: boolean;
+}) => ImproveRecord;
+/**
+ * The stage's paid work is in flight, priced, and written down before it can
+ * fail (F19).
+ *
+ * `improve.json` is the kit's spend ledger, and it only ever held stages that
+ * SETTLED. The pipedrive kit dispatched two parent conversions and settled
+ * neither, so its recorded ceiling was the draft's $0.242 and the lane had to
+ * publish a planning proxy in place of a receipt. A stage already recorded is
+ * left alone: a resume re-attaches to the conversion this entry paid for.
+ */
+export declare const noteImproveStageDispatched: (args: {
+    record: ImproveRecord;
+    stage: ImproveStage;
+    priceCeilingUsd: number;
+}) => ImproveRecord;
 export declare const markImproveStageSkipped: (record: ImproveRecord, stage: ImproveStage) => Promise<ImproveRecord>;
 //# sourceMappingURL=improve-stage-shared.d.ts.map

package/dist/improve-stage-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"improve-stage-shared.d.ts","sourceRoot":"","sources":["../src/improve-stage-shared.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,OAAO,UAAU,KAAG,MAA0D,CAAC;AAE7G,eAAO,MAAM,gBAAgB,GAAU,MAAM;IAC3C,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;CAChB,KAAG,OAAO,CAAC,aAAa,CAmBxB,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,aAAa,EACrB,OAAO,YAAY,KAClB,OAAO,CAAC,aAAa,CAOtB,CAAC"}
+{"version":3,"file":"improve-stage-shared.d.ts","sourceRoot":"","sources":["../src/improve-stage-shared.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,4EAA4E;IAC5E,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,OAAO,UAAU,KAAG,MAA0D,CAAC;AAE7G;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,OAAO,YAAY,KAClB,mBAIF,CAAC;AAOF,eAAO,MAAM,gBAAgB,GAAU,MAAM;IAC3C,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;CAChB,KAAG,OAAO,CAAC,aAAa,CA+BxB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB,KAAG,aAcH,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,KAAG,aAaH,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,QAAQ,aAAa,EACrB,OAAO,YAAY,KAClB,OAAO,CAAC,aAAa,CAOtB,CAAC"}

package/dist/improve-stage-shared.js

@@ -2,20 +2,49 @@ import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { writeImproveRecord, } from './improve-workspace.js';
 export const improveSha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/**
+ * The word for what this stage did, read off the record it just wrote (F28).
+ *
+ * The facts were always there — `convert.layout`, `convert.responsiveWarning`,
+ * `plan.gate` — and the README already printed them. Only `improve.json` said
+ * `settled` over a fixed-layout fallback and a gate-blocked plan, which is the
+ * one place a supervisor or a campaign parser looks.
+ */
+export const improveStageOutcome = (record, stage) => {
+    if (stage === 'convert' && record.convert?.layout === 'fixed')
+        return 'fallback';
+    if (stage === 'plan' && record.plan?.gate === 'blocked')
+        return 'blocked';
+    return 'settled';
+};
+/** A priced entry whose paid call has not come back yet. */
+const isPendingOutcome = (outcome) => (outcome === 'dispatched' || outcome === 'stalled');
 export const noteImproveStage = async (args) => {
     const previous = args.record.stages[args.stage];
+    // A stage recorded at DISPATCH is not a replay of anything: the paid call it
+    // priced is the one settling now, so settling completes that entry rather
+    // than counting a second run of the stage. A stage that STALLED holds the
+    // same entry — the resume is that call finishing, not a second run of it.
+    const pending = previous && isPendingOutcome(previous.outcome) ? previous : undefined;
+    const outcome = args.outcome ?? improveStageOutcome(args.record, args.stage);
     const record = {
         ...args.record,
         stages: {
             ...args.record.stages,
-            [args.stage]: previous ? {
+            [args.stage]: previous && !pending ? {
                 ...previous,
                 replayCount: previous.replayCount + (args.replayed ? 1 : 0),
+                // A replay re-reads the outcome too, so a kit written before this
+                // field could tell the truth stops calling a fallback settled the
+                // first time it is resumed.
+                outcome,
             } : {
+                ...(pending?.dispatchedAt ? { dispatchedAt: pending.dispatchedAt } : {}),
                 settledAt: new Date().toISOString(),
                 replayCount: 0,
-                priceCeilingUsd: args.priceCeilingUsd,
-                outcome: args.outcome ?? 'settled',
+                // The dispatch priced this call; a settlement never prices it lower.
+                priceCeilingUsd: Math.max(pending?.priceCeilingUsd ?? 0, args.priceCeilingUsd),
+                outcome,
             },
         },
     };
@@ -23,6 +52,54 @@ export const noteImproveStage = async (args) => {
         await writeImproveRecord(path.join(args.record.runDir, 'improve.json'), record);
     return record;
 };
+/**
+ * The paid call this stage dispatched did not come back in this run.
+ *
+ * It rewrites the dispatched entry rather than adding one, so the price stays
+ * the price of the call that is still running and a resume still re-attaches
+ * to it. A stage with no entry bought nothing; it gets an unpriced `stalled`
+ * entry only when the run itself stalled, so `stages.plan.outcome` can say so
+ * instead of staying silent.
+ */
+export const markImproveStageStalled = (args) => {
+    const previous = args.record.stages[args.stage];
+    if (previous && previous.outcome !== 'dispatched')
+        return args.record;
+    if (!previous && !args.stalled)
+        return args.record;
+    return {
+        ...args.record,
+        stages: {
+            ...args.record.stages,
+            [args.stage]: {
+                ...(previous ?? { replayCount: 0, priceCeilingUsd: 0 }),
+                outcome: 'stalled',
+            },
+        },
+    };
+};
+/**
+ * The stage's paid work is in flight, priced, and written down before it can
+ * fail (F19).
+ *
+ * `improve.json` is the kit's spend ledger, and it only ever held stages that
+ * SETTLED. The pipedrive kit dispatched two parent conversions and settled
+ * neither, so its recorded ceiling was the draft's $0.242 and the lane had to
+ * publish a planning proxy in place of a receipt. A stage already recorded is
+ * left alone: a resume re-attaches to the conversion this entry paid for.
+ */
+export const noteImproveStageDispatched = (args) => (args.record.stages[args.stage] ? args.record : {
+    ...args.record,
+    stages: {
+        ...args.record.stages,
+        [args.stage]: {
+            dispatchedAt: new Date().toISOString(),
+            replayCount: 0,
+            priceCeilingUsd: args.priceCeilingUsd,
+            outcome: 'dispatched',
+        },
+    },
+});
 export const markImproveStageSkipped = async (record, stage) => noteImproveStage({
     record,
     stage,

package/dist/improve-stage-shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"improve-stage-shared.js","sourceRoot":"","sources":["../src/improve-stage-shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAM7B,OAAO,EACL,kBAAkB,GAGnB,MAAM,wBAAwB,CAAC;AAchC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAiB,EAAU,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAE7G,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,IAOtC,EAA0B,EAAE;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,MAAM,GAAkB;QAC5B,GAAG,IAAI,CAAC,MAAM;QACd,MAAM,EAAE;YACN,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;YACrB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;gBACvB,GAAG,QAAQ;gBACX,WAAW,EAAE,QAAQ,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAC5D,CAAC,CAAC,CAAC;gBACF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,WAAW,EAAE,CAAC;gBACd,eAAe,EAAE,IAAI,CAAC,eAAe;gBACrC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,SAAS;aACnC;SACF;KACF,CAAC;IACF,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IAChG,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,EAC1C,MAAqB,EACrB,KAAmB,EACK,EAAE,CAAC,gBAAgB,CAAC;IAC5C,MAAM;IACN,KAAK;IACL,eAAe,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,SAAS;IACrD,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,IAAI;CACZ,CAAC,CAAC"}
+{"version":3,"file":"improve-stage-shared.js","sourceRoot":"","sources":["../src/improve-stage-shared.ts"],"names":[],"mappings":"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"}

package/dist/improve-stop-handler.d.ts

@@ -0,0 +1,73 @@
+import { type ImproveLiveStage, type ImproveStopSignal } from './improve-terminal-event.js';
+import type { RunJournalNotes } from './run-journal.js';
+import { type ImproveRecord, type ImproveStage } from './improve-workspace.js';
+/**
+ * A stopped run owes the same kit a stalled run owes, and the same record.
+ *
+ * The pipedrive lane killed a conversion at 97 seconds. Nothing threw, so no
+ * README, no `plan/STALL.md`, no end-of-run summary and no terminal journal
+ * event were ever written, and the reader was left with an empty `target/` and
+ * a PNG — the exact starting condition that produced a hand-authored hero.
+ * Ctrl-C is not a silent exit.
+ *
+ * The handler is armed for the WHOLE run, not just the delivery stages: a kill
+ * during capture, draft or pick used to leave nothing at all. The stage it
+ * reports comes from the LIVE invocation first and the record only second —
+ * see `ImproveLiveStage`, and the pipedrive kit of 2026-09-02, where a record
+ * left settled by an earlier replay read as complete while a `--fresh`
+ * conversion this process had dispatched was still in flight.
+ *
+ * WHAT THIS PATH DOES NOT WRITE: `improve.json`. It reads it, and never the
+ * other way round. Making a stopped `--fresh` or retry conversion resumable
+ * needs its idempotency key on the record, and the convert stage puts it there
+ * BEFORE it dispatches (`improve-conversion-attempts.ts`) — so by the time a
+ * signal arrives the fact is already durable, and a record write racing a
+ * second signal after the journal end line buys nothing.
+ */
+export type { ImproveStopSignal };
+export type ImproveStopArtifacts = {
+    /** Absent when nothing was in flight and every stage in range had settled. */
+    stage?: ImproveStage;
+    /** Absent for the same reason: a complete kit is owed no STALL.md. */
+    stall?: string;
+    readme: string;
+    summary: string;
+    errorClass: string;
+};
+export declare const writeImproveStopArtifacts: (args: {
+    record: ImproveRecord;
+    signal: ImproveStopSignal;
+    requestedTo?: ImproveStage;
+    journal?: RunJournalNotes;
+    /** The stage this invocation entered and had not finished. See `ImproveLiveStage`. */
+    live?: ImproveStage;
+}) => Promise<ImproveStopArtifacts>;
+export type ImproveStopTarget = {
+    once: (signal: ImproveStopSignal, listener: () => void) => unknown;
+    off: (signal: ImproveStopSignal, listener: () => void) => unknown;
+};
+/**
+ * Arm the stop path and return the disarm function. The record is read through
+ * a getter because the caller reassigns it as each stage settles, and the kit
+ * written on the way out has to describe the record as it stands at the moment
+ * of the stop.
+ *
+ * What this cannot do: SIGKILL, which a lane timeout may send, runs no handler
+ * at all. That case leaves the journal's last progress line as the record, and
+ * `12ui next` reads it as an unfinished paid run — which is the truth.
+ */
+export declare const registerImproveStopHandler: (args: {
+    getRecord: () => ImproveRecord;
+    /**
+     * The stage this invocation is inside right now. Without it the handler can
+     * only ask the record, which a `--fresh` conversion in flight makes a liar.
+     */
+    getLiveStage?: ImproveLiveStage;
+    write: (line: string) => void;
+    requestedTo?: ImproveStage;
+    journal?: RunJournalNotes;
+    onStopped?: (result: ImproveStopArtifacts) => void;
+    target?: ImproveStopTarget;
+    exit?: (code: number) => void;
+}) => (() => void);
+//# sourceMappingURL=improve-stop-handler.d.ts.map

package/dist/improve-stop-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-stop-handler.d.ts","sourceRoot":"","sources":["../src/improve-stop-handler.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAKF,eAAO,MAAM,yBAAyB,GAAU,MAAM;IACpD,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,sFAAsF;IACtF,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,KAAG,OAAO,CAAC,oBAAoB,CA+D/B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;IACnE,GAAG,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;CACnE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM;IAC/C,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACnD,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B,KAAG,CAAC,MAAM,IAAI,CAuCd,CAAC"}

package/dist/improve-stop-handler.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import { writeImproveReadme } from './improve-kit-readme.js';
+import { writeImproveStallReport } from './improve-kit-stall.js';
+import { buildImproveRunSummary } from './improve-run-summary.js';
+import { improveUnsettledStage, IMPROVE_SIGNALLED_AFTER_COMPLETION, noteImproveTerminalEvent, } from './improve-terminal-event.js';
+import { improvePaths, readImproveRecord, } from './improve-workspace.js';
+/** Exit codes for a signalled stop are 128 plus the signal number. */
+const EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+export const writeImproveStopArtifacts = async (args) => {
+    // WHAT DECIDES. Live invocation state first, the record only when this
+    // invocation has nothing in flight. A stage this process is still inside is
+    // proof the run is not complete, whatever the record says — and after
+    // `--fresh` the record says the opposite, because the clear it wrote to disk
+    // has not reached the copy held here. "Signalled after completion" is only
+    // true when no stage is in flight AND every requested stage has settled.
+    const stage = args.live ?? improveUnsettledStage(args.record, args.requestedTo);
+    const context = args.requestedTo ? { requestedTo: args.requestedTo } : {};
+    const paths = improvePaths(args.record.runDir);
+    // The handler stays armed until the `finally` block, so a signal can land
+    // after the last requested stage has settled. That run is complete: writing
+    // "# INCOMPLETE — this run was stopped" over it, and journalling a stop that
+    // leaves a hosted run open, is the kit lying in the opposite direction from
+    // the pipedrive defect. It gets the terminal line, the README and the
+    // ordinary summary, and no STALL.md.
+    if (!stage) {
+        const errorClass = await noteImproveTerminalEvent({
+            record: args.record,
+            stage: args.requestedTo ?? 'plan',
+            kind: 'stopped',
+            error: new Error(`The run was stopped with ${args.signal} after every requested stage settled.`),
+            signal: args.signal,
+            errorClass: IMPROVE_SIGNALLED_AFTER_COMPLETION,
+            writes: [paths.readme],
+            ...(args.journal ? { journal: args.journal } : {}),
+        });
+        return {
+            readme: await writeImproveReadme(args.record, context),
+            summary: await buildImproveRunSummary({ record: args.record, ...context }),
+            errorClass,
+        };
+    }
+    const error = new Error(`The run was stopped with ${args.signal} before ${stage} settled.`);
+    // The record closes FIRST. Everything after this is a filesystem write that a
+    // second signal can cut short; the journal line cannot be written later.
+    const errorClass = await noteImproveTerminalEvent({
+        record: args.record,
+        stage,
+        kind: 'stopped',
+        error,
+        signal: args.signal,
+        writes: [path.join(paths.planDir, 'STALL.md'), paths.readme],
+        ...(args.live ? { inFlight: true } : {}),
+        ...(args.journal ? { journal: args.journal } : {}),
+    });
+    // The kit is written from the DURABLE record, the way the stall path in
+    // `cli-improve-command.ts` already does: a stage in flight has written down
+    // what it abandoned and what it cleared, and the in-memory copy predates
+    // that. It is read only AFTER the end line, so the one-read-before-the-end
+    // rule this module's header states still holds.
+    const durable = await readImproveRecord(paths.record) ?? args.record;
+    const stall = await writeImproveStallReport({
+        record: durable,
+        stage,
+        error,
+        kind: 'stopped',
+        ...(args.live ? { inFlight: true } : {}),
+        ...context,
+    });
+    const readme = await writeImproveReadme(durable, context);
+    const summary = await buildImproveRunSummary({ record: durable, ...context });
+    return { stage, stall, readme, summary, errorClass };
+};
+/**
+ * Arm the stop path and return the disarm function. The record is read through
+ * a getter because the caller reassigns it as each stage settles, and the kit
+ * written on the way out has to describe the record as it stands at the moment
+ * of the stop.
+ *
+ * What this cannot do: SIGKILL, which a lane timeout may send, runs no handler
+ * at all. That case leaves the journal's last progress line as the record, and
+ * `12ui next` reads it as an unfinished paid run — which is the truth.
+ */
+export const registerImproveStopHandler = (args) => {
+    const target = args.target ?? process;
+    const exit = args.exit ?? ((code) => { process.exit(code); });
+    const signals = ['SIGINT', 'SIGTERM'];
+    let stopping = false;
+    const listeners = new Map();
+    const disarm = () => {
+        for (const [signal, listener] of listeners)
+            target.off(signal, listener);
+        listeners.clear();
+    };
+    for (const signal of signals) {
+        const listener = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            disarm();
+            void (async () => {
+                try {
+                    const live = args.getLiveStage?.();
+                    const result = await writeImproveStopArtifacts({
+                        record: args.getRecord(),
+                        signal,
+                        ...(live ? { live } : {}),
+                        ...(args.requestedTo ? { requestedTo: args.requestedTo } : {}),
+                        ...(args.journal ? { journal: args.journal } : {}),
+                    });
+                    args.write(result.summary);
+                    args.onStopped?.(result);
+                }
+                catch (error) {
+                    // Say so rather than exiting quietly: an unwritten kit that also
+                    // said nothing is the failure this whole path exists to end.
+                    args.write(`Could not write the stopped kit: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                exit(EXIT_CODE[signal]);
+            })();
+        };
+        listeners.set(signal, listener);
+        target.once(signal, listener);
+    }
+    return disarm;
+};
+//# sourceMappingURL=improve-stop-handler.js.map

package/dist/improve-stop-handler.js.map

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