npm - @rubytech/create-maxy-code - Versions diffs - 0.1.97 → 0.1.98 - Mend

@rubytech/create-maxy-code 0.1.97 → 0.1.98

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/payload/platform/plugins/founder-pack/skills/investor-data-room/references/html-pdf-pipeline.md ADDED Viewed

@@ -0,0 +1,236 @@
+# HTML + PDF render pipeline
+Image-only A4 portrait PDF, rendered from a single HTML file via Playwright + img2pdf + qpdf. Mirrors the constraints in the `property-brochure:a4-print-documents` skill.
+## File layout per artefact
+```
+html/<artefact>/
+  index.html        # source of truth
+  render-pdf.mjs    # Playwright pipeline
+  <artefact>.pdf    # rendered output
+  logo-light.png    # for dark cover/backpage
+  logo-dark.png     # for light content pages (optional)
+  README.md         # render + verify commands, page list
+```
+## HTML scaffold (key blocks)
+```html
+<!DOCTYPE html>
+<html lang="en-GB">
+<head>
+  <meta charset="UTF-8">
+  <link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Inter:wght@400;500;600;700&family=Lora:ital,wght@0,400;0,500;0,600;1,400&display=swap" rel="stylesheet">
+  <style>
+    /* Tier 1 + Tier 2 design tokens from project's design-tokens.md */
+    :root {
+      --teal-900: #0E1418;
+      --teal-950: #06080A;
+      --gold-500: #A4884C;
+      --gold-300: #C9B07A;
+      --gold-700: #7A6235;
+      --paper-0:  #FFFFFF;
+      --paper-25: #FBFAF6;
+      --paper-100: #ECF1F2;
+      --slate-400: #8A8E96;
+      --slate-600: #5C6470;
+      --rule-fine: #E2D5BD;
+      --serif: 'Cormorant Garamond', serif;
+      --body-serif: 'Lora', Georgia, serif;
+      --sans: 'Inter', sans-serif;
+      --surface-page: var(--paper-25);
+      --surface-deep: var(--teal-950);
+      --text-primary: var(--teal-900);
+      --text-on-deep: var(--paper-25);
+      --text-accent: var(--gold-700);
+      --text-accent-on-deep: var(--gold-300);
+    }
+    @page { size: A4 portrait; margin: 18mm 16mm 20mm; }
+    @page :first { margin: 0; }
+    @page backpage-full { margin: 0; }
+    body {
+      margin: 0;
+      background: var(--surface-page);
+      color: var(--text-primary);
+      font-family: var(--body-serif);
+      font-size: 11pt;
+      line-height: 1.55;
+      counter-reset: pagenum;
+    }
+    .page {
+      counter-increment: pagenum;
+      position: relative;
+    }
+    .page:not(.page--cover):not(.page--backpage)::after {
+      content: counter(pagenum);
+      position: absolute;
+      bottom: 10mm;
+      right: 16mm;
+      font-family: var(--sans);
+      font-size: 9pt;
+      letter-spacing: 0.28em;
+      color: var(--slate-400);
+    }
+    .page:not(.page--cover):not(.page--backpage)::before {
+      content: "REAL AGENT NETWORK LIMITED · BUSINESS PLAN · v1.0";
+      position: absolute;
+      bottom: 10mm;
+      left: 16mm;
+      font-family: var(--sans);
+      font-size: 7pt;
+      letter-spacing: 0.24em;
+      color: var(--slate-400);
+    }
+    @media screen {
+      body { background: #FFFFFF; padding: 24px; }
+      .page {
+        width: 210mm; min-height: 297mm;
+        margin: 20px auto; padding: 18mm 16mm 20mm;
+        background: var(--surface-page);
+        box-shadow: 0 4px 28px rgba(0,0,0,0.14);
+      }
+      .page--cover, .page--backpage { padding: 0; overflow: hidden; }
+    }
+    @media print {
+      body { background: var(--surface-page); padding: 0; }
+      .page { page-break-after: always; padding: 0; }
+      .page--cover, .page--backpage {
+        margin: 0; width: auto; box-shadow: none;
+        height: 100vh; position: relative; overflow: hidden;
+        -webkit-print-color-adjust: exact;
+        print-color-adjust: exact;
+      }
+      .page--backpage { page-break-before: always; page: backpage-full; }
+      .download-btn { display: none !important; }
+    }
+    .download-btn {
+      position: fixed; top: 20px; right: 20px; z-index: 100;
+      font-family: var(--sans); font-size: 9pt; letter-spacing: 0.28em;
+      text-transform: uppercase; color: var(--paper-0);
+      background: var(--teal-900); padding: 11px 18px 12px;
+      border-radius: 9999px; text-decoration: none;
+      box-shadow: 0 4px 16px rgba(14, 20, 24, 0.18);
+    }
+    .download-btn:hover { background: var(--gold-700); }
+  </style>
+</head>
+<body>
+  <a class="download-btn" href="<artefact>.pdf" download>Download PDF</a>
+  <section class="page page--cover" data-screen-label="cover"> ... </section>
+  <section class="page" data-screen-label="exec-summary"> ... </section>
+  <!-- ... one <section class="page"> per A4 page ... -->
+  <section class="page page--backpage" data-screen-label="backpage"> ... </section>
+</body>
+</html>
+```
+## render-pdf.mjs (canonical)
+```javascript
+#!/usr/bin/env node
+import { chromium } from 'playwright';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, rmSync, existsSync } from 'node:fs';
+import { dirname, basename, join, resolve, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [, , htmlInput, pdfOutput] = process.argv;
+if (!htmlInput || !pdfOutput) {
+  console.error('Usage: render-pdf.mjs <input.html> <output.pdf>');
+  process.exit(64);
+}
+const htmlPath = resolve(htmlInput);
+const pdfPath  = resolve(pdfOutput);
+const tmpDir = resolve(dirname(pdfPath), `.tmp-${basename(pdfPath, extname(pdfPath))}`);
+rmSync(tmpDir, { recursive: true, force: true });
+mkdirSync(tmpDir, { recursive: true });
+const VIEWPORT_W = 794;        // A4 portrait at 96 dpi
+const VIEWPORT_H = 1123;
+const SCALE = 3.125;           // → 300 dpi PNGs
+const A4_HEIGHT_PX_SLACK = VIEWPORT_H + 2;
+(async () => {
+  const browser = await chromium.launch();
+  const context = await browser.newContext({
+    viewport: { width: VIEWPORT_W, height: VIEWPORT_H },
+    deviceScaleFactor: SCALE,
+  });
+  const page = await context.newPage();
+  await page.goto(pathToFileURL(htmlPath).toString(), { waitUntil: 'networkidle' });
+  await page.emulateMedia({ media: 'print' });
+  await page.evaluate(() => document.fonts ? document.fonts.ready : Promise.resolve());
+  await page.evaluate(() => { document.body.style.padding = '0'; });
+  const sections = await page.$$('section.page');
+  if (sections.length === 0) {
+    console.error('No <section class="page"> elements found.');
+    process.exit(65);
+  }
+  const pngFiles = [];
+  let overflow = false;
+  for (let i = 0; i < sections.length; i++) {
+    const section = sections[i];
+    const label = await section.getAttribute('data-screen-label') || `page${i + 1}`;
+    const scrollHeight = await section.evaluate(el => el.scrollHeight);
+    if (scrollHeight > A4_HEIGHT_PX_SLACK) {
+      console.error(`[OVERFLOW] page ${i + 1} (${label}): ${scrollHeight}px > A4 + 2px slack`);
+      overflow = true;
+    }
+    const outPath = join(tmpDir, `page-${String(i + 1).padStart(2, '0')}-${label}.png`);
+    await section.scrollIntoViewIfNeeded();
+    await section.screenshot({ path: outPath, type: 'png' });
+    pngFiles.push(outPath);
+  }
+  await browser.close();
+  if (overflow) {
+    console.error('Overflow detected. Aborting.');
+    process.exit(4);
+  }
+  const preLinearize = join(tmpDir, 'pre-linearize.pdf');
+  execFileSync('img2pdf', ['--pagesize', '210mmx297mm', '--output', preLinearize, ...pngFiles], { stdio: 'inherit' });
+  execFileSync('qpdf', ['--linearize', '--object-streams=disable', preLinearize, pdfPath], { stdio: 'inherit' });
+  console.log(`✓ PDF written: ${pdfPath}`);
+})();
+```
+## Verification
+After every render:
+```sh
+qpdf --check <artefact>.pdf                           # → "No syntax or stream encoding errors found"
+pdfinfo  <artefact>.pdf | grep -E "Pages|Optimized"   # → confirms page count + linearization
+```
+Then **read every page visually**. `pdfinfo` reporting "25 pages, A4" is not verification.
+## Dependencies
+```sh
+npm i -D playwright && npx playwright install chromium
+brew install img2pdf qpdf
+```
+## Hard rules
+- One `<section class="page">` per A4 page. Renderer aborts (exit 4) on overflow.
+- `execFileSync` (never `execSync` with template strings).
+- Cover and backpage are full-bleed dark teal (`--surface-deep`); skip page numbers and running footer via `:not(.page--cover):not(.page--backpage)` selectors on the page-counter pseudo-elements.
+- Even page count for booklet binding (multiple of 4 ideal).
+- Logo: copy the white-mono icon variant as `logo-light.png` for dark cover/backpage; copy the dark icon variant as `logo-dark.png` if used on light content pages.

package/payload/platform/plugins/founder-pack/skills/investor-data-room/references/internal-workings-scrub.md ADDED Viewed

@@ -0,0 +1,33 @@
+# Internal-workings scrub — public-vs-internal doctrine
+Public-facing documents (business plan, prospectus, deck, term sheet, anything the investor reads) state the **current position** only. The journey to that position, the reasoning behind it, comparisons against prior baselines, open items still being reconciled, and cross-references to internal sections all stay in working documents in the data-room's internal sections.
+## Patterns that must NOT appear in public docs
+- **Comparison to baseline / prior version.** *"The loss has grown from -£282.6k to -£323.1k because…"*, *"Total opex (M0 customer-success hire adds £40,500 vs the M10 model worksheet baseline)"*.
+- **Process commentary.** *"Numbers below use the model's published figures pending the reconciled rebuild"*, *"reconciliation pending"*, *"open item, not actioned here"*, *"see Section X critical note and Section Y contingency levers for the reconciliation paths"*.
+- **Internal cross-references to scaffolding.** *"see Section 12.3 critical note"*, *"see Section 12.6 contingency levers"* when the linked content itself is process-talk rather than substance.
+- **Discrepancy resolution narratives.** *"The earlier '£0.01 vs £0.001 nominal' note is resolved by treating the £4,500 as share premium"*.
+- **"Open Q" or "Open item" markers in body text.** Belongs in section READMEs and the office-hours design doc only.
+- **Date-coded internal designs.** *"2026-04-22 design"*, *"office-hours design doc"*, *"model worksheet (Appendix A) needs a rebuild"*.
+- **"Pre-contingency-lever activation" / "once X is included" hedges in summary tables.**
+- **Explanatory parentheticals that name the process.** *"(M10-trigger model did not carry)"* is process commentary and must go.
+## What IS acceptable in a public-facing document
+- The current position, stated as a fact.
+- A footnote citing a source (Companies House, IBISWorld, ICO, etc.) when the figure derives from public data.
+- A pointer to a public appendix (titled documents only; not internal-section READMEs).
+- Conditions on a forecast figure that an investor needs to know (e.g. "assuming Round 2 closes at M9-M10").
+## The same content, internal vs public
+| Internal version (working doc) | Public version (business plan) |
+|---|---|
+| Total operating expenses ~£649,100 (M0 customer-success hire adds £40,500 vs the M10 model worksheet baseline). | Total operating expenses ~£649,100. |
+| Year-1 P&L loss has grown from -£282.6k to -£323.1k because the customer-success hire is brought forward from M10 to M0. | Year-1 P&L loss is approximately £323k against revenue of £356k. |
+| Cash crosses zero at M8–M9 if Round 2 does not close; the model worksheet's M11 £34k cash low arrives roughly two months earlier under the M0 CS hire structure. | The raise is sized to deliver the Round 2 gating milestones; Round 2 closes at M9 to M10. |
+## Recurrence is a P0 violation
+In the reference project this rule was violated three times in one session (initial draft used a dated internal design reference; appendix table referenced internal-only documents alongside externally-shareable ones; M0 customer-success hire updates added "model worksheet baseline" comparisons). The pattern: every time the founder adds content or asks for an update, the temptation is to include "what changed and why" alongside the new value. The temptation must be resisted; the public document carries only the new value. The "what changed and why" goes in a sibling internal document if it needs to live somewhere.

package/payload/platform/services/claude-session-manager/dist/http-server.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,EAYL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAKzB,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAoB9E;4CAC4C;AAC5C,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;~~AA6ED~~,eAAO,MAAM,kBAAkB,QAAoC,CAAA;~~AAQnE~~,eAAO,MAAM,uBAAuB,QAA4B,CAAA;AAIhE,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;CAC/B;AAqID;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,~~CAi3CpD~~"}
1	+ {"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,EAYL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAKzB,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAoB9E;4CAC4C;AAC5C,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AA8ED,eAAO,MAAM,kBAAkB,QAAoC,CAAA;AASnE,eAAO,MAAM,uBAAuB,QAA4B,CAAA;AAIhE,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;CAC/B;AAqID;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CA62CpD"}

package/payload/platform/services/claude-session-manager/dist/http-server.js CHANGED Viewed

@@ -132,21 +132,23 @@ function parseSpecialistDomains(raw) {
     return out.length > 0 ? out : undefined;
 }
 // `<id>` may be: intrinsic UUID, bridgeSessionId ("session_<suffix>"),
-// bridgeSuffix, pid (numeric), or the resume-conflict stash composite
-// id `<uuid>.<unix-ms>` minted at http-server.ts:1006/1013 and surfaced
-// by Task 260's archive enumerator. Dot is admitted; length raised to
-// fit UUID (36) + `.` + 13-digit ms; the negative lookahead rejects
-// all-dot strings so path-traversal shapes (`.`, `..`, `...`) cannot
-// satisfy the gate. No `/` — Hono's route param already excludes it,
-// and admitting it here would broaden the filesystem surface the
-// downstream `jsonlPathForSessionId` composition trusts.
+// bridgeSuffix, pid (numeric), or a legacy stash composite id
+// `<uuid>.<unix-ms>` left on disk by pre-Task-273 code (the platform
+// no longer mints them) and still surfaced by Task 260's archive
+// enumerator. Dot is admitted; length raised to fit UUID (36) + `.` +
+// 13-digit ms; the negative lookahead rejects all-dot strings so
+// path-traversal shapes (`.`, `..`, `...`) cannot satisfy the gate.
+// No `/` — Hono's route param already excludes it, and admitting it
+// here would broaden the filesystem surface the downstream
+// `jsonlPathForSessionId` composition trusts.
 export const SESSION_ID_PATTERN = /^(?!\.+$)[A-Za-z0-9._-]{1,160}$/;
-// Task 263 — stash-composite IDs are minted at http-server.ts:1013 when
-// a resume-conflict preserves a smaller JSONL at `<uuid>.<unix-ms>` in
-// the archive directory. They are addressable (Task 262 admitted them
-// at the HTTP gate) but not resumable: `claude --resume` expects a
-// UUID, not a composite. The pattern lower-bounds the digit run at 13
-// to match the millisecond timestamp the writer emits.
+// Task 263 / Task 273 — stash-composite IDs were minted by the
+// pre-Task-273 resume-conflict and promote-displacement paths at
+// `<uuid>.<unix-ms>`. Task 273 removed both minting sites; this
+// pattern now matches only legacy on-disk composites and is the gate
+// the /resume and /promote routes use to refuse or promote them. The
+// pattern lower-bounds the digit run at 13 to match the millisecond
+// timestamp the prior writer emitted.
 export const STASH_COMPOSITE_PATTERN = /^[a-f0-9-]{36}\.\d{13}$/;
 const LIST_TAIL_BYTES = 64 * 1024;
 function timed(logger, method, path, status, ms) {
@@ -900,10 +902,15 @@ export function buildHttpApp(deps) {
             : undefined;
         const sourceRow = resolveRow(deps.watcher, sessionId);
         const specialist = bodySpecialist ?? sourceRow?.agent ?? undefined;
-        // Task 258 — restore the archived jsonl to its canonical top-level path
-        // before claude --resume runs. Claude appends to `<projectsDir>/<sid>.jsonl`;
-        // if the file lives in `archive/`, claude doesn't find it and starts a fresh
-        // empty transcript at the top-level path, silently splitting the conversation.
+        // Task 258 / Task 273 — restore the archived jsonl to its canonical
+        // top-level path before claude --resume runs. Claude CLI manages
+        // resume natively as one file per UUID: it appends to
+        // `<projectsDir>/<sid>.jsonl`. If the file lives in `archive/`,
+        // claude doesn't find it and starts a fresh empty transcript at the
+        // top-level path, silently splitting the conversation. The platform
+        // does not synthesise `<uuid>.<unix-ms>` stash composites — when
+        // both archived and canonical exist, that is an invariant break, not
+        // a parallel fork to recover.
         const canonicalJsonl = jsonlPathForSessionId(deps.spawnCwd, sessionId);
         const archivedJsonl = jsonlPathForSessionId(deps.spawnCwd, sessionId, { archived: true });
         const canonicalExists = existsSync(canonicalJsonl);
@@ -934,32 +941,22 @@ export function buildHttpApp(deps) {
             }
         }
         else if (archivedExists && canonicalExists) {
-            // Both files exist — pre-Task-258 bug already produced two parallel
-            // jsonls for one sessionId. Keep the larger as canonical (more history);
-            // park the smaller at `archive/<sid>.<ts>.jsonl`. No data loss.
-            try {
-                const canonicalSize = statSync(canonicalJsonl).size;
-                const archivedSize = statSync(archivedJsonl).size;
-                const keepArchived = archivedSize > canonicalSize;
-                const ts = Date.now();
-                if (keepArchived) {
-                    const stash = jsonlPathForSessionId(deps.spawnCwd, `${sessionId}.${ts}`, { archived: true });
-                    renameSync(canonicalJsonl, stash);
-                    renameSync(archivedJsonl, canonicalJsonl);
-                    deps.logger(`resume-conflict sessionId=${sessionId.slice(0, 8)} resolution=keep-archived canonical-size=${canonicalSize} archived-size=${archivedSize} stashed=${stash}`);
-                }
-                else {
-                    const stash = jsonlPathForSessionId(deps.spawnCwd, `${sessionId}.${ts}`, { archived: true });
-                    renameSync(archivedJsonl, stash);
-                    deps.logger(`resume-conflict sessionId=${sessionId.slice(0, 8)} resolution=keep-canonical canonical-size=${canonicalSize} archived-size=${archivedSize} stashed=${stash}`);
-                }
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                deps.logger(`resume-conflict-resolve-failed sessionId=${sessionId.slice(0, 8)} message=${msg}`);
-                timed(deps.logger, 'POST', '/resume', 500, Date.now() - start);
-                return c.json({ error: 'resume-restore-failed', detail: msg }, 500);
-            }
+            // Task 273 — both files exist. The pre-Task-258 minting bug is
+            // closed; if we see this state, an external write has put us back
+            // in the split-conversation regime. Refuse loudly. The operator
+            // resolves on the filesystem (typically: keep the larger, quarantine
+            // the smaller — same rule the Pi cleanup script applies), then
+            // retries resume. No stash composite is minted by this code path.
+            const canonicalSize = statSync(canonicalJsonl).size;
+            const archivedSize = statSync(archivedJsonl).size;
+            deps.logger(`[http-server] resume-collision-detected sessionId=${sessionId.slice(0, 8)} canonical-size=${canonicalSize} archived-size=${archivedSize}`);
+            timed(deps.logger, 'POST', '/resume', 500, Date.now() - start);
+            return c.json({
+                error: 'resume-collision-detected',
+                detail: 'both archive/<sid>.jsonl and top-level <sid>.jsonl exist — resolve on disk before retrying',
+                canonicalSize,
+                archivedSize,
+            }, 500);
         }
         const result = await spawnClaudeSession({
             ...deps,
@@ -1138,9 +1135,13 @@ export function buildHttpApp(deps) {
     //
     // Promotes a stash-composite JSONL (`<uuid>.<unix-ms>.jsonl`) back to
     // its canonical UUID path (`<uuid>.jsonl`) so a normal `/resume` against
-    // the UUID can re-attach a PTY to the preserved conversation. The
-    // resume-conflict path (Task 258) mints stash composites; this is the
-    // door that opens before `/resume` can fire on one.
+    // the UUID can re-attach a PTY to the preserved conversation.
+    //
+    // Task 273 — the platform no longer mints stash composites; resume and
+    // promote both refuse rather than rename canonical aside. Existing
+    // stash composites on disk (left by the pre-Task-273 minting bug) are
+    // promotable only when the canonical UUID has no jsonl AND no live
+    // PTY. Anything else is an operator-resolves state.
     //
     // Deterministic refusals, no spawn attempted:
     //   400 invalid-session-id        — pattern check fails
@@ -1148,18 +1149,22 @@ export function buildHttpApp(deps) {
     //   409 pty-still-alive-on-canonical — isLive(uuid) is true; clobbering
     //                                  the canonical jsonl would corrupt
     //                                  the live PTY's transcript
+    //   409 canonical-already-populated — canonical `<uuid>.jsonl` exists
+    //                                  on disk (no live PTY). The operator
+    //                                  resolves on the filesystem (purge,
+    //                                  or move the canonical aside manually)
+    //                                  before retrying promote.
     //   409 stash-ambiguous-location  — the same stash id exists both at
     //                                  the project root AND under archive/
     //   404 stash-not-found           — neither location has the file
     //                                  (raced with Purge in another tab)
     //
     // Happy path:
-    //   - If canonical `<uuid>.jsonl` exists, rename it aside to
-    //     `<uuid>.<Date.now()>.jsonl` (top-level) first, preserving the
-    //     displaced history as a fresh stash sibling — same rule as
-    //     Task 258's resume-conflict path.
     //   - renameSync(stashPath, canonicalPath); sidecar follows.
-    //   - 200 { canonicalSessionId, displacedStashId }
+    //   - 200 { canonicalSessionId, displacedStashId: null }
+    //   displacedStashId is always null in the new contract; the field
+    //   stays on the wire for client compatibility but never carries a
+    //   non-null value.
     app.post('/:sessionId/promote', async (c) => {
         const start = Date.now();
         const id = c.req.param('sessionId');
@@ -1208,35 +1213,26 @@ export function buildHttpApp(deps) {
             : sidecarPathForSessionId(deps.spawnCwd, id, { archived: true });
         const canonicalJsonl = jsonlPathForSessionId(deps.spawnCwd, uuid);
         const canonicalSidecar = sidecarPathForSessionId(deps.spawnCwd, uuid);
-        // Conflict resolution — displace canonical to a fresh stash sibling
-        // at the project root. Sidecar follows. Same rule as the
-        // resume-conflict path in /resume (Task 258).
-        let displacedStashId = null;
+        // Task 273 — refuse on canonical-already-populated. The pre-Task-273
+        // displacement path renamed the canonical aside to a fresh
+        // `<uuid>.<unix-ms>` sibling and compounded the on-disk debris. The
+        // new contract is: promote only when the canonical slot is empty.
+        // If a file sits there with no live PTY, the operator chose to keep
+        // it (purge would have removed it); resolving the collision is an
+        // operator decision, not a silent rename.
         if (existsSync(canonicalJsonl)) {
-            const ts = Date.now();
-            const displacedId = `${uuid}.${ts}`;
-            const displacedJsonl = jsonlPathForSessionId(deps.spawnCwd, displacedId);
-            const displacedSidecar = sidecarPathForSessionId(deps.spawnCwd, displacedId);
-            try {
-                renameSync(canonicalJsonl, displacedJsonl);
-                if (existsSync(canonicalSidecar)) {
-                    try {
-                        renameSync(canonicalSidecar, displacedSidecar);
-                    }
-                    catch (err) {
-                        deps.logger(`[http-server] promote-displace-sidecar-failed sessionId=${id.slice(0, 8)} message=${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-                displacedStashId = displacedId;
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                deps.logger(`[http-server] promote-displace-failed sessionId=${id.slice(0, 8)} message=${msg}`);
-                timed(deps.logger, 'POST', `/${id}/promote`, 500, Date.now() - start);
-                return c.json({ error: 'promote-failed', detail: msg }, 500);
-            }
+            const canonicalSize = statSync(canonicalJsonl).size;
+            deps.logger(`[http-server] promote-refused sessionId=${id.slice(0, 8)} reason=canonical-already-populated uuid=${uuid.slice(0, 8)} canonical-size=${canonicalSize}`);
+            timed(deps.logger, 'POST', `/${id}/promote`, 409, Date.now() - start);
+            return c.json({
+                error: 'canonical-already-populated',
+                detail: `canonical <uuid>.jsonl exists on disk (${canonicalSize} bytes) — purge or manually resolve before retrying promote`,
+                canonicalSessionId: uuid,
+                canonicalSize,
+            }, 409);
         }
-        // Promote — stash → canonical. Sidecar follows.
+        // Promote — stash → canonical. Sidecar follows. No prior displacement
+        // means no displacedStashId can ever be non-null.
         try {
             renameSync(stashJsonl, canonicalJsonl);
             if (existsSync(stashSidecar)) {
@@ -1250,17 +1246,13 @@ export function buildHttpApp(deps) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            // Forensic completeness: when the canonical was already displaced
-            // before this throw, the operator must know where the original
-            // canonical now lives on disk. Without `displacedStashId` here, the
-            // 500 looks like "promote did nothing" — recoverable but opaque.
-            deps.logger(`[http-server] promote-failed sessionId=${id.slice(0, 8)} displaced-stash=${displacedStashId ?? 'null'} message=${msg}`);
+            deps.logger(`[http-server] promote-failed sessionId=${id.slice(0, 8)} message=${msg}`);
             timed(deps.logger, 'POST', `/${id}/promote`, 500, Date.now() - start);
-            return c.json({ error: 'promote-failed', detail: msg, displacedStashId }, 500);
+            return c.json({ error: 'promote-failed', detail: msg, displacedStashId: null }, 500);
         }
-        deps.logger(`[http-server] promote sessionId=${id.slice(0, 8)} uuid=${uuid.slice(0, 8)} displaced-stash=${displacedStashId ? displacedStashId.slice(0, 8) : 'null'}`);
+        deps.logger(`[http-server] promote sessionId=${id.slice(0, 8)} uuid=${uuid.slice(0, 8)} displaced-stash=null`);
         timed(deps.logger, 'POST', `/${id}/promote`, 200, Date.now() - start);
-        return c.json({ canonicalSessionId: uuid, displacedStashId }, 200);
+        return c.json({ canonicalSessionId: uuid, displacedStashId: null }, 200);
     });
     // Task 253 — POST /:sessionId/rename { title }
     //   - 200 + body on accept (carries the persisted title)