mikser-io 9.66.0 → 9.70.0

package/CLAUDE.md

@@ -200,6 +200,28 @@ brevity.
   of folder names written in the plugin. A hardcoded list misses every
   collection a project registers through `sources()`, which produced 63
   false warnings per build on a real site.
+- `src/plugins/render/asset.js` / `resource.js` — URL helpers that BUILD
+  a path from a naming convention instead of looking an entity up, so
+  they cannot fail: a preset that never ran yields a well-formed link to
+  nothing on a green build. Each records its destination via
+  `track.asset()`; `engine.js` checks the collected set against
+  `outputFolder` in `onFinalized` (`reportAssetUse` / `assetUse` in
+  report.js, `reportMissingAssets` in engine.js), warning under
+  `asset-missing` / `asset-missing-summary`. `existsSync` FOLLOWS
+  symlinks, which is required — the assets folder is deployed into the
+  output as a symlink. Handlebars appends an options object to every
+  helper call, so a trailing optional arg (`format`) must be discarded
+  when it looks like one (`'hash' in format`); without that, `asset 'web'
+  '/x.jpg'` built `/assets/web/x.[object Object]` — the bug the finalize
+  check found on its first run, present since the helper took a format.
+- Postprocess failures are RENDER ERRORS. The dispatcher's catch used to
+  log one uncoded `Postprocess error:` line and stop there — exit code 0,
+  nothing in `--json` `errors`, `🟢 Mikser completed`. A build missing
+  every PDF it was asked for reported success. It now calls `reportError`
+  with the failing `postprocessor`, so a stage that wrote no file counts
+  the same as a render that threw. `entity.origin` is deliberately NOT
+  unlinked on failure (it is on success): a retry needs it as input, and
+  for a converter it is real content.
 - `render.js` / `postprocess.js` — Piscina worker entry points AND the
   default-export functions the INLINE/SERIAL dispatcher calls directly.
   Each receives entity + options + config + state; the WORKER path also
@@ -242,7 +264,14 @@ brevity.
   EINVAL`. chmod 0600, so the filesystem permission is the access
   decision. A forwarded build RESCANS (`runtime.rebuild()`), never
   drains: a client can beat the inotify event for the file it just
-  wrote. Exit code comes from `renderErrorCount()`, not
+  wrote. Report-only commands (`--tool`, `--tools`, `--verify`,
+  `--explain`) forward too — they read, so a local run damaged nothing,
+  but a catalogue another process is mid-write in is not one anyone can
+  answer from. `runReportOnly()` in engine.js is the one implementation
+  both paths call. `--server` / `--watch` are NOT forwardable — they ask
+  to BECOME the instance, and a running engine cannot open a port on
+  someone's behalf — so they exit 1 with a message when one is already
+  there. Exit code comes from `renderErrorCount()`, not
   `process.exitCode` — the engine suppresses that in watch mode by
   design. Config mismatch is refused by resolved PATH; config drift
   under a running instance is detected by stat over `configCoverage`.

package/app.js

@@ -2,7 +2,7 @@
 import path from 'node:path'
 
 import { setup } from './index.js'
-import { forward } from './src/instance.js'
+import { forward, isInstanceLive } from './src/instance.js'
 
 // Before anything is imported or read.
 //
@@ -24,27 +24,60 @@ function locate(argv) {
         }
         return null
     }
-    const has = (...names) => names.some(n => argv.includes(n))
+    const has = (...names) => names.some(n => argv.includes(n) || argv.some(a => names.some(x => a.startsWith(`${x}=`))))
+
+    // Asking to BECOME the instance, rather than asking one for something.
+    // Not forwardable in principle: a running engine cannot open a listener on
+    // someone else's behalf, and forwarding it built, printed "completed" and
+    // exited with nothing on the port.
+    const longRunning = has('--watch', '-w', '--server', '-s')
+
+    // What to ask the instance for. Report-only commands go over the same
+    // socket as a build: they read, so running them locally never damaged
+    // anything, but a catalogue being written by another process is not a
+    // catalogue anyone can answer from — a --verify against a half-finished
+    // cycle reports drift that is not there.
+    const tool = value('--tool')
+    const explain = value('--explain')
+    const request = has('--tools') ? { type: 'report', tools: true, json: has('--json') }
+        : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json') }
+        : explain                 ? { type: 'report', explain, json: has('--json') }
+        : has('--verify')         ? { type: 'report', verify: true, json: has('--json') }
+        : { type: 'build', clear: has('--clear') }
+
     return {
+        longRunning,
         workingFolder: value('--working-folder', '-i') ?? '.',
         config: value('--config', '-c') ?? 'mikser.config.js',
-        clear: has('--clear'),
         // Commander's negated form: `attach` is true unless --no-attach said so.
         attach: has('--no-attach') ? false : true,
-        // Report-only runs read; they do not write the catalogue or the output
-        // tree, and their handlers exit the process themselves. Left local —
-        // the guard in setup() still says an instance is there.
-        reportOnly: has('--tool', '--tools', '--verify', '--explain'),
+        request,
     }
 }
 
 async function main() {
     const where = locate(process.argv.slice(2))
-    if (where.attach !== false && !where.reportOnly) {
+    const workingFolder = path.resolve(where.workingFolder)
+
+    // A second server or watcher is the hazard this whole surface exists to
+    // remove, and it is the one shape that cannot be answered by forwarding.
+    // So it stops, rather than silently doing something else.
+    if (where.attach !== false && where.longRunning) {
+        if (await isInstanceLive(workingFolder)) {
+            process.stderr.write(
+                'mikser: another mikser is already running in this folder, and a server or watcher cannot be '
+                + 'forwarded to it — it would have to open a port on your behalf.\n'
+                + 'Stop that one, or pass --no-attach to run a second engine here (two engines share the '
+                + 'catalogue and the output tree, with no lock between them).\n')
+            process.exit(1)
+        }
+    }
+
+    if (where.attach !== false && !where.longRunning) {
         const code = await forward({
-            workingFolder: path.resolve(where.workingFolder),
+            workingFolder,
             config: path.resolve(where.workingFolder, where.config),
-            clear: where.clear,
+            request: where.request,
         })
         // null means nobody was listening — carry on exactly as before.
         if (code !== null) process.exit(code)

package/docs/diagnostics.md

@@ -756,9 +756,21 @@ Three things it refuses or reports rather than guessing:
 - **A config that moved under the instance.** It stats every file in
   `config.files` and tells you to restart rather than building with a config
   you have since edited.
+- **A second server or watcher.** `mikser --server` and `mikser --watch` ask
+  to *become* the instance, which is not something a running one can do for
+  you — it would have to open a port in your process. They exit 1 and say so,
+  rather than building and leaving nothing on the port.
 - **A folder held by someone else.** `--no-attach` runs a private engine
   anyway — for checking that a cold start works — and says the folder is held.
 
+`--tool`, `--tools`, `--verify` and `--explain` forward as well, and for a
+different reason than builds do. They only read, so running one locally never
+damaged anything — it just could not be trusted: on a large site a local
+`--verify` reads a catalogue the instance is halfway through writing and
+reports drift that is a cycle in progress. The instance has the settled state
+and the config that produced it. Exit codes cross the socket unchanged, so
+`--explain` still answers 3 for an entity that is not there.
+
 A forwarded build **rescans**; it does not drain what the watcher happened to
 queue. A client that writes a file and immediately asks can beat the file
 event, and draining would then build without the change that prompted the
@@ -838,10 +850,11 @@ surfaces that turn silence into a statement:
 - **A pattern or query that matched nothing** — several plugins warn on
   this now (layout patterns, preset matching, null filters). The warnings
   carry stable `code`s in `--json`.
-- **Output that does not match the config** — the config's bytes take
-  part in cache invalidation, so a config change forces a rebuild; but a
-  module the config *imports* does not. If you changed a helper the config
-  pulls in, use `--force`.
+- **Output that does not match the config** — the config's checksum
+  covers the local module graph it imports, not just its own bytes, so
+  editing a helper the config pulls in forces a rebuild the same way
+  editing the config does. A change *outside* that graph — inside an npm
+  dependency — still does not, so use `--force` after upgrading one.
 - **A tool that answers emptily because it is broken** — check
   [`faults`](#faults) before reading an empty result as a fact about the
   site. This is the one case where the answer and the failure are the same
@@ -849,6 +862,21 @@ surfaces that turn silence into a statement:
 - **A plugin that appears to do nothing** — `No plugins loaded` with a
   config present is a warning naming the file. A config that fails to
   load now exits non-zero rather than loading as empty.
+- **A postprocess that could not run** — a stage whose external
+  dependency is absent (no chrome for a PDF, no binary for a conversion)
+  reports a fault naming the subsystem, and each page that wanted that
+  output fails as an ordinary render error. The fault says why once; the
+  errors say who, and set the exit code. A missing dependency does not
+  fail the whole build — the HTML is already written and correct — but it
+  does not pass as clean either.
+- **A link to a file nothing produced** — helpers like `asset()` and
+  `resource()` *build* a URL from a naming convention rather than looking
+  an entity up, so they cannot fail: a preset that never ran, or a
+  template naming an extension the preset no longer emits, yields a
+  well-formed URL to nothing. Every such call is recorded on the render
+  track and checked against the output folder at finalize; what is missing
+  is warned under `asset-missing`, naming the path and the pages that
+  linked it.
 
 ## See also
 

package/docs/rendering.md

@@ -375,6 +375,25 @@ Generates relative URLs to transformed assets (output of the assets plugin). Ret
 
 The underlying path is: `/{assetsFolder}/{preset}/{path}[.{format}]`
 
+#### Checked against the output
+
+The path is *built* from that convention, not looked up, so the helper
+cannot fail — it returns a well-formed URL whether or not anything ever
+produced the file. A preset that did not run, a source that is not
+matched by the preset's patterns, or a template naming a format the
+preset no longer emits all yield a link to nothing, on a build that
+reports success.
+
+So every `asset()` and `resource()` call records its destination on the
+render track, and at finalize the engine checks each one against the
+output folder. Anything missing is warned under the `asset-missing` code,
+naming the path and the pages that linked it, with a summary under
+`asset-missing-summary`. The check follows symlinks, so an assets folder
+deployed into the output as a link resolves normally.
+
+It is a warning, not an error: a build can legitimately link a file that
+some later step supplies. What it removes is the silence.
+
 ---
 
 ### `render-resource` — CDN Resource Mapping
@@ -542,6 +561,16 @@ Return shapes the dispatcher accepts:
 
 A chain is all-or-nothing. The first stage to throw or return `{success: false}` fails the entry; the dispatcher unlinks every intermediate it produced and the final destination, then re-throws. No partial output leaks.
 
+The renderer's own output (`entity.origin`) is the exception: on success the
+dispatcher unlinks it, on failure it stays. It is the input a retry needs, and
+for a converter it is content in its own right — the HTML of a report whose PDF
+could not be produced.
+
+A failed entry counts as a **render error**: it lands in `errors` under `--json`
+with the failing `postprocessor` named, and sets the exit code. It wrote no
+file, so it has to count the same as a render that threw — otherwise a build
+missing every PDF it was asked for reports success.
+
 ### Execution mode
 
 Postprocess inherits the layout's `task:` setting. `task: worker` routes both render and postprocess through the lazy Piscina pool (right for CPU-heavy stages: PDF, image compose, big MJML compilations). Default INLINE is right for everything else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.66.0",
+  "version": "9.70.0",
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/engine.js

@@ -11,7 +11,7 @@ import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
 import { changeExtension, formatErrorContext, projectMeta, lookupKeys } from './utils.js'
-import { reportRendered, reportSkipped, reportError, renderErrorCount, emitReport, finishCycle } from './report.js'
+import { reportRendered, reportSkipped, reportError, renderErrorCount, emitReport, finishCycle, reportAssetUse, assetUse } from './report.js'
 import { toolSchemas, invokeTool, toolResultText, toolResultFailed } from './tools.js'
 import { registerBuiltinTools } from './builtin-tools.js'
 import { useDatabase } from './database/index.js'
@@ -89,6 +89,164 @@ function workerSafeOptions(opts) {
     return result
 }
 
+// Warn for anything a render linked to that is not in the output.
+//
+// Deliberately phrased as what was OBSERVED. Only entities that rendered this
+// cycle recorded anything, so an incremental build checks the pages it built
+// and says nothing about the rest — the same reasoning the assets plugin
+// already applies to its preset warning, and for the same reason: a warning
+// that overclaims gets filtered, and the filtered-out line is the real one.
+async function reportMissingAssets(logger) {
+    const used = assetUse()
+    if (!used.length) return
+    const outputFolder = runtime.options.outputFolder
+    if (!outputFolder) return
+
+    const missing = []
+    for (const [destination, ids] of used) {
+        const file = path.join(outputFolder, destination.replace(/^\//, ''))
+        if (!existsSync(file)) missing.push([destination, ids])
+    }
+    if (!missing.length) return
+
+    // Capped, with the total alongside. One broken preset can be referenced by
+    // every page on the site, and a thousand lines of it buries whatever else
+    // the build said.
+    const SHOWN = 10
+    for (const [destination, ids] of missing.slice(0, SHOWN)) {
+        logger.warn({ code: 'asset-missing', destination, referencedBy: ids },
+            'Linked but not in the output: %s — referenced by %s', destination,
+            ids.slice(0, 3).join(', ') + (ids.length > 3 ? ` and ${ids.length - 3} more` : ''))
+    }
+    logger.warn({ code: 'asset-missing-summary', missing: missing.length, checked: used.length },
+        '%d of %d linked file(s) are not in the output%s. A URL helper builds the path rather than looking it '
+        + 'up, so this is a link to something nothing produced — usually a preset that did not run, or a '
+        + 'template naming an extension the preset no longer emits.',
+        missing.length, used.length,
+        missing.length > SHOWN ? `, ${SHOWN} shown` : '')
+}
+
+// The report-only commands, as functions that RETURN their exit code.
+//
+// They used to be inline here and call process.exit, which is fine for a
+// process whose only job is to answer one question and stop. It is not fine
+// for the instance that has to answer the same question on behalf of a client
+// and stay alive — and answering it there is the point, because a local run
+// reads a catalogue another process is in the middle of writing.
+//
+// `request` carries the CLIENT's arguments. Reading runtime.options here would
+// answer with the instance's own flags, which are whatever it happened to be
+// started with.
+export async function runReportOnly(request = {}) {
+    const logger = useLogger()
+    const {
+        tools = runtime.options.tools,
+        tool = runtime.options.tool,
+        toolArgs = runtime.options.toolArgs,
+        json = runtime.options.json,
+        explain = runtime.options.explain,
+        verify = runtime.options.verify,
+    } = request
+
+    if (tools) {
+        const schemas = toolSchemas()
+        if (json) {
+            process.stdout.write(JSON.stringify(schemas, null, 2) + '\n')
+        } else if (!schemas.length) {
+            logger.warn('No tools registered. The mcp plugin registers the standard set; '
+                + 'this flag only lists and invokes what is registered.')
+        } else {
+            for (const schema of schemas) {
+                process.stdout.write(`${schema.name}\n    ${String(schema.description).split('\n')[0]}\n`)
+            }
+        }
+        return 0
+    }
+
+    if (tool) {
+        // An empty catalog answers every question with a confident nothing —
+        // `null`, `total: 0`, "no render claims this destination" — all of
+        // which read as "the thing you asked about does not exist" when the
+        // truth is "nothing has been built here yet". Said once, before the
+        // answer, so it cannot be missed.
+        const entityCount = (() => {
+            try {
+                return useDatabase().handle
+                    .prepare('SELECT count(*) AS n FROM mikser_entities').get()?.n ?? 0
+            } catch { return null }
+        })()
+        if (entityCount === 0 && !runtime.manifest?.size?.()) {
+            logger.warn('The catalog and manifest are empty — no build has run in this working '
+                + 'folder. Tools answer from what the last build recorded, so this one will '
+                + 'report nothing found. Run a build first.')
+        }
+
+        let args = {}
+        if (toolArgs) {
+            try {
+                args = JSON.parse(toolArgs)
+            } catch (err) {
+                logger.error('--tool-args is not valid JSON: %s', err.message)
+                return 3
+            }
+        }
+        let result
+        try {
+            result = await invokeTool(tool, args)
+        } catch (err) {
+            logger.error('%s', err.message)
+            return 3
+        }
+        process.stdout.write(toolResultText(result) + '\n')
+        // A tool that reports failure must not exit 0 — an agent reading CLI
+        // output has only the exit code to branch on.
+        return toolResultFailed(result) ? 1 : 0
+    }
+
+    if (explain) {
+        // Exit codes:
+        //   0 — the entity was found and described
+        //   3 — not in the catalog (distinct from --verify's 1/2, which are
+        //       about output drift; "no such entity" is neither clean nor
+        //       corrupt, it is a question that could not be answered)
+        const { explain: explainEntity, formatExplain } = await import('./explain.js')
+        const report = await explainEntity(explain)
+        process.stdout.write((json ? JSON.stringify(report, null, 2) : formatExplain(report)) + '\n')
+        return report.found ? 0 : 3
+    }
+
+    if (verify) {
+        if (!runtime.manifest) {
+            logger.error('Verify: no manifest available — nothing to check against')
+            return 2
+        }
+        const { verdict, missing, mismatched, unverifiable, orphaned, collisions } =
+            await runtime.manifest.verify()
+        const total = runtime.manifest.size()
+
+        for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
+        for (const e of mismatched)   logger.error('Mismatched: %s (entity %s)%s', e.destination, e.id,
+            e.writtenBy ? ` — the bytes on disk are ${e.writtenBy}'s` : '')
+        for (const e of unverifiable) logger.warn('No hash:    %s (entity %s)', e.destination, e.id)
+        for (const e of orphaned)     logger.warn('Orphan:     %s', e.path)
+        // Named per destination: "two entities write here" is only actionable
+        // if you know which two.
+        for (const c of collisions)   logger.warn('Collision:  %s ← %s', c.destination, c.entities.join(', '))
+
+        // Level picked from the verdict, because the level IS the marker in
+        // pino-pretty's messageFormat: notice renders 🟢, warn 🟡, error 🔴. A
+        // fixed `notice` prints a green tick next to the word FAIL, which
+        // reads as success at a glance even though the exit code is right.
+        const report = verdict === 'FAIL' ? logger.error : verdict === 'WARN' ? logger.warn : logger.notice
+        report.call(logger,
+            'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned, %d collisions',
+            verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length, collisions.length)
+        return verdict === 'FAIL' ? 2 : verdict === 'WARN' ? 1 : 0
+    }
+
+    return null   // not a report-only request
+}
+
 export async function setup(options) {
     runtime.options.threads = options?.threads !== undefined ? options.threads : 4
     runtime.engine = {
@@ -291,57 +449,8 @@ export async function setup(options) {
         // registry is complete. Nothing is imported, because this exits first,
         // the same way --explain and --verify do.
         if (runtime.options.tools || runtime.options.tool) {
-            if (runtime.options.tools) {
-                const schemas = toolSchemas()
-                if (runtime.options.json) {
-                    process.stdout.write(JSON.stringify(schemas, null, 2) + '\n')
-                } else if (!schemas.length) {
-                    logger.warn('No tools registered. The mcp plugin registers the standard set; '
-                        + 'this flag only lists and invokes what is registered.')
-                } else {
-                    for (const schema of schemas) {
-                        process.stdout.write(`${schema.name}\n    ${String(schema.description).split('\n')[0]}\n`)
-                    }
-                }
-                process.exit(0)
-            }
-            // An empty catalog answers every question with a confident
-            // nothing — `null`, `total: 0`, "no render claims this
-            // destination" — all of which read as "the thing you asked about
-            // does not exist" when the truth is "nothing has been built here
-            // yet". Said once, before the answer, so it cannot be missed.
-            const entityCount = (() => {
-                try {
-                    return useDatabase().handle
-                        .prepare('SELECT count(*) AS n FROM mikser_entities').get()?.n ?? 0
-                } catch { return null }
-            })()
-            if (entityCount === 0 && !runtime.manifest?.size?.()) {
-                logger.warn('The catalog and manifest are empty — no build has run in this working '
-                    + 'folder. Tools answer from what the last build recorded, so this one will '
-                    + 'report nothing found. Run a build first.')
-            }
-
-            let args = {}
-            if (runtime.options.toolArgs) {
-                try {
-                    args = JSON.parse(runtime.options.toolArgs)
-                } catch (err) {
-                    logger.error('--tool-args is not valid JSON: %s', err.message)
-                    process.exit(3)
-                }
-            }
-            let result
-            try {
-                result = await invokeTool(runtime.options.tool, args)
-            } catch (err) {
-                logger.error('%s', err.message)
-                process.exit(3)
-            }
-            process.stdout.write(toolResultText(result) + '\n')
-            // A tool that reports failure must not exit 0 — an agent reading
-            // CLI output has only the exit code to branch on.
-            process.exit(toolResultFailed(result) ? 1 : 0)
+            const code = await runReportOnly()
+            if (code !== null) process.exit(code)
         }
     })
 
@@ -368,58 +477,11 @@ export async function setup(options) {
         //   3 — not in the catalog (distinct from --verify's 1/2, which are
         //       about output drift; "no such entity" is neither clean nor
         //       corrupt, it is a question that could not be answered)
-        if (runtime.options.explain) {
-            const { explain, formatExplain } = await import('./explain.js')
-            const report = await explain(runtime.options.explain)
-            if (runtime.options.json) {
-                process.stdout.write(JSON.stringify(report, null, 2) + '\n')
-            } else {
-                process.stdout.write(formatExplain(report) + '\n')
-            }
-            process.exit(report.found ? 0 : 3)
-        }
-
-        if (runtime.options.explain) {
-            const { explain, formatExplain } = await import('./explain.js')
-            const report = await explain(runtime.options.explain)
-            if (runtime.options.json) {
-                process.stdout.write(JSON.stringify(report, null, 2) + '\n')
-            } else {
-                process.stdout.write(formatExplain(report) + '\n')
-            }
-            process.exit(report.found ? 0 : 3)
-        }
-
-
-        if (runtime.options.verify) {
-            if (!runtime.manifest) {
-                logger.error('Verify: no manifest available — nothing to check against')
-                process.exit(2)
-            }
-            const { verdict, missing, mismatched, unverifiable, orphaned, collisions } =
-                await runtime.manifest.verify()
-            const total = runtime.manifest.size()
-
-            for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
-            for (const e of mismatched)   logger.error('Mismatched: %s (entity %s)%s', e.destination, e.id,
-                e.writtenBy ? ` — the bytes on disk are ${e.writtenBy}'s` : '')
-            for (const e of unverifiable) logger.warn('No hash:    %s (entity %s)', e.destination, e.id)
-            for (const e of orphaned)     logger.warn('Orphan:     %s', e.path)
-            // Named per destination: "two entities write here" is only
-            // actionable if you know which two.
-            for (const c of collisions)   logger.warn('Collision:  %s ← %s', c.destination, c.entities.join(', '))
-
-            // Level picked from the verdict, because the level IS the marker
-            // in pino-pretty's messageFormat: notice renders 🟢, warn 🟡,
-            // error 🔴. A fixed `notice` prints a green tick next to the word
-            // FAIL, which reads as success at a glance even though the exit
-            // code is right.
-            const report = verdict === 'FAIL' ? logger.error : verdict === 'WARN' ? logger.warn : logger.notice
-            report.call(logger,
-                'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned, %d collisions',
-                verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length, collisions.length)
-            process.exit(verdict === 'FAIL' ? 2 : verdict === 'WARN' ? 1 : 0)
-        }
+        // The same three commands the instance answers over the socket —
+        // one implementation, so a forwarded --verify cannot disagree with a
+        // local one about what it checked.
+        const code = await runReportOnly()
+        if (code !== null) process.exit(code)
     })
 
     onRender(async (signal) => {
@@ -652,6 +714,15 @@ export async function setup(options) {
                     result = rendered?.output
                     if (rendered?.track) mergeTrack(track, rendered.track)
 
+                    // Which files this entity's template linked to. Harvested
+                    // here because this is the one place that has both the
+                    // track and the entity that produced it — a worker's track
+                    // has just been folded in, so a worker render is covered
+                    // the same as an inline one.
+                    for (const destination of track.assets ?? []) {
+                        reportAssetUse(destination, renderEntity.id)
+                    }
+
                     if (!signal.aborted) {
                         // Meta reads ride on `output`, which is already
                         // free-form JSON on the journal row, rather than in
@@ -989,6 +1060,17 @@ export async function setup(options) {
                         if (!signal.aborted) {
                             await updateEntry({ id, output: { success: false } })
                             logger.error('Postprocess error: %s%s %s', entity.id, formatErrorContext(entity, err, runtime.options), err.message)
+                            // A failed postprocess wrote no file, so it has to
+                            // count the same as a failed render. It did not:
+                            // this line was the whole of it, the exit code
+                            // stayed 0, and `errors` in --json never mentioned
+                            // it — a build with output missing reporting
+                            // success, which is the exact shape of bug the
+                            // rest of this file exists to make impossible.
+                            reportError(entity, err, {
+                                postprocessor: options.postprocessor ?? null,
+                                layout: entity.layout?.id ?? null,
+                            })
                         }
                         logger.debug('Postprocess canceled')
                     }
@@ -1045,6 +1127,19 @@ export async function setup(options) {
         if (failed) logger.error('Mikser completed with %d render error%s', failed, failed === 1 ? '' : 's')
         else logger.notice('Mikser completed')
 
+        // Is everything the templates linked to actually there?
+        //
+        // The URL helpers build paths; they do not resolve them. So a preset
+        // that never ran, a library that was not copied, or a template naming
+        // an extension the preset stopped producing all yield a well-formed
+        // link to a file that does not exist — and the only symptom is a
+        // missing image on the deployed site, found by a person.
+        //
+        // Checked at the end of the cycle because that is the first moment the
+        // answer is stable: derivatives are produced during the cycle, so
+        // asking any earlier would report files that were about to appear.
+        await reportMissingAssets(useLogger())
+
         // After the cycle, and only under --json. stdout has been kept clear
         // for exactly this (the logger writes to stderr under --json), so the
         // document is the only thing on it and can be piped to jq.

package/src/instance.js

@@ -34,6 +34,7 @@ import { chmod } from 'node:fs/promises'
 import runtime from './runtime.js'
 import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
+import { runReportOnly } from './engine.js'
 
 // Where the endpoint lives.
 //
@@ -66,7 +67,8 @@ export function socketPath(workingFolder) {
 // Newline-delimited JSON, one object per line. Deliberately boring: both ends
 // ship together, so there is nothing to negotiate and no version to carry.
 //
-//   → { type: 'build', config, clear }
+//   → { type: 'build',  config, clear }
+//   → { type: 'report', config, tool, tools, toolArgs, explain, verify, json }
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
 //   ← { type: 'refused', reason, detail }
@@ -97,7 +99,7 @@ function readFrames(socket, onFrame) {
 // which case the caller proceeds exactly as it always did. Called before
 // setup(), so a forwarded command never pays for importing the config or the
 // plugin graph, which is most of what a one-shot spends its time on.
-export function forward({ workingFolder, config, clear }) {
+export function forward({ workingFolder, config, request }) {
     const endpoint = socketPath(workingFolder)
 
     return new Promise((resolve) => {
@@ -116,7 +118,7 @@ export function forward({ workingFolder, config, clear }) {
             resolve(null)
         })
 
-        socket.on('connect', () => frame(socket, { type: 'build', config, clear }))
+        socket.on('connect', () => frame(socket, { ...request, config }))
 
         readFrames(socket, (message) => {
             if (message.type === 'log') {
@@ -147,6 +149,35 @@ export function forward({ workingFolder, config, clear }) {
     })
 }
 
+// Is somebody already holding this folder?
+//
+// Used by the commands that cannot be forwarded because they are not requests
+// at all — `--server` and `--watch` ask to BECOME the instance. Forwarding one
+// builds and exits, and the port never opens: the caller asked for a server on
+// 3010, got "completed", and has nothing listening.
+//
+// Same stale-socket rule as forward(): connect-and-fail means nobody is there,
+// never a wait.
+export function isInstanceLive(workingFolder) {
+    const endpoint = socketPath(workingFolder)
+    return new Promise((resolve) => {
+        const probe = net.connect(endpoint)
+        let settled = false
+        const answer = (live) => {
+            if (settled) return
+            settled = true
+            try { probe.destroy() } catch { /* already gone */ }
+            if (!live && process.platform !== 'win32' && existsSync(endpoint)) {
+                try { unlinkSync(endpoint) } catch { /* another client won the race */ }
+            }
+            resolve(live)
+        }
+        probe.on('connect', () => answer(true))
+        probe.on('error', () => answer(false))
+        setTimeout(() => answer(false), 1000).unref?.()
+    })
+}
+
 // ── server ──────────────────────────────────────────────────────────────
 
 // Requests run one at a time, to completion.
@@ -219,29 +250,50 @@ async function configStale() {
     return null
 }
 
-async function serveBuild(socket, request, logger) {
-    const wrongConfig = configMismatch(request.config)
-    if (wrongConfig) {
-        frame(socket, {
-            type: 'refused',
-            reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
-            detail: 'Forwarding would build with the wrong config — the accident this refusal exists to prevent. '
-                + 'Stop that instance, or pass --no-attach to run your own.',
-        })
-        return
+// Report-only commands, answered from the live catalogue.
+//
+// These read; they do not write, so running them locally was safe for the
+// FILES. It was not safe for the ANSWER. A local --verify at ten thousand
+// pages reads a catalogue the instance is in the middle of writing and reports
+// drift that is a half-finished cycle, and a local --tool answers from
+// whatever the last build left rather than from what is true now.
+//
+// The instance has the settled state and the config that produced it, so it is
+// the only process that can answer correctly. Same guards as a build: wrong
+// config refuses, drifted config refuses.
+async function serveReport(socket, request, logger) {
+    const restore = captureOutput((chunk) => frame(socket, { type: 'log', chunk }))
+    let code = 0
+    try {
+        code = await runReportOnly(request) ?? 0
+    } catch (err) {
+        logger?.error('instance: forwarded report failed — %s', err.message)
+        code = 3
+    } finally {
+        restore()
     }
+    frame(socket, { type: 'done', code })
+}
 
-    const movedFile = await configStale()
-    if (movedFile) {
-        frame(socket, {
-            type: 'refused',
-            reason: `this instance's config changed on disk since it started (${movedFile}).`,
-            detail: 'It is still building with the old one. Restart it, and this command will reach an '
-                + 'instance that matches what you edited.',
-        })
-        return
-    }
+function refuseConfig(socket, request, wrongConfig) {
+    frame(socket, {
+        type: 'refused',
+        reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
+        detail: 'Answering would use the wrong config — the accident this refusal exists to prevent. '
+            + 'Stop that instance, or pass --no-attach to run your own.',
+    })
+}
 
+function refuseStale(socket, movedFile) {
+    frame(socket, {
+        type: 'refused',
+        reason: `this instance's config changed on disk since it started (${movedFile}).`,
+        detail: 'It is still running the old one. Restart it, and this command will reach an instance that '
+            + 'matches what you edited.',
+    })
+}
+
+async function serveBuild(socket, request, logger) {
     const restore = captureOutput((chunk) => frame(socket, { type: 'log', chunk }))
     let code = 0
     try {
@@ -304,8 +356,20 @@ export function serveInstance() {
         server = net.createServer((socket) => {
             socket.on('error', () => { /* client vanished mid-request */ })
             readFrames(socket, (request) => {
-                if (request.type !== 'build') return
-                chain = chain.then(() => serveBuild(socket, request, logger)).catch(() => {})
+                if (request.type !== 'build' && request.type !== 'report') return
+                chain = chain.then(async () => {
+                    // Both kinds answer for the client's config, not the
+                    // instance's — a report against the wrong config is the
+                    // original incident, and it is wrong whether or not it
+                    // writes anything.
+                    const wrongConfig = configMismatch(request.config)
+                    if (wrongConfig) return refuseConfig(socket, request, wrongConfig)
+                    const movedFile = await configStale()
+                    if (movedFile) return refuseStale(socket, movedFile)
+                    return request.type === 'build'
+                        ? serveBuild(socket, request, logger)
+                        : serveReport(socket, request, logger)
+                }).catch(() => {})
             })
         })
         server.on('error', (err) => {
@@ -374,10 +438,17 @@ export async function warnIfHeld({ workingFolder, attached }) {
 export function instanceControl() {
     serveInstance()
     onLoaded(async () => {
-        if (runtime.options.watch || runtime.options.server) return
+        // Only --no-attach reaches this now. Everything else either forwarded
+        // (a build, a report) or refused before setup ran (a second server or
+        // watcher), so a process that is still here and not attaching is one
+        // that deliberately opted out — and that is exactly the case worth
+        // saying something about, long-running or not. The earlier gate
+        // skipped watch and server, which excluded `--no-attach --server`:
+        // the very command that puts two engines on one folder.
+        if (runtime.options.attach !== false) return
         await warnIfHeld({
             workingFolder: runtime.options.workingFolder,
-            attached: runtime.options.attach,
+            attached: false,
         })
     })
 }

package/src/plugins/assets.js

@@ -231,6 +231,13 @@ export function assets(options = {}) {
             for (let entityPreset of assetsMap[entityToRender.id] || []) {
                 const entity = _.cloneDeep(entityToRender)
                 entity.preset = presets[entityPreset]
+                // Named in config but with no module in presets/ and no
+                // mikser-io-preset-* package: there is nothing to render with.
+                // Loading already reported this preset ('Preset not found'),
+                // and the finalize check names the links left dangling. A line
+                // per entity here would just be that fact a third time, once
+                // per matched file.
+                if (!entity.preset) continue
                 // Per-preset config options override the preset module's
                 // defaults. Looked up at render time so config edits are
                 // picked up on the next cycle without rebuilding the

package/src/plugins/render/asset.js

@@ -15,7 +15,7 @@ import { changeExtension } from '../../utils.js'
 // derivative may simply not have been generated, and this cannot tell.
 // `meta.presets` (ADR-0011) is the looked-up answer where a caller has the
 // entity; this helper exists for the case where they have a path.
-export function load({ runtime, entity, state, options, logger }) {
+export function load({ runtime, entity, state, options, logger, track }) {
     const presets = state?.assets?.presets ?? {}
     const warned = new Set()
     const warnOnce = (key, code, message, ...args) => {
@@ -27,6 +27,15 @@ export function load({ runtime, entity, state, options, logger }) {
     runtime.asset = (preset, url, format) => {
         if (url[0] != '/') url = `/${url}`
 
+        // Handlebars appends its own options object to every helper call, so a
+        // two-argument `{{asset 'web' '/media/hero.jpg'}}` arrives here with a
+        // third. Taken as a format it stringifies, and the helper cheerfully
+        // built `hero.[object Object]` — a well-formed link to a file that
+        // could never exist. file.js strips it for the same reason; this one
+        // never did, and nothing noticed until the output check started
+        // looking at what these URLs point at.
+        if (format && typeof format === 'object' && 'hash' in format) format = undefined
+
         const declared = presets[preset]?.format
 
         // A preset name nothing declares. The URL still gets built — it is a
@@ -57,6 +66,11 @@ export function load({ runtime, entity, state, options, logger }) {
         // happened to be rendering.
         const relative = `${state.assets.assetsFolder}/${preset}${effective ? changeExtension(url, effective) : url}`
         const destination = '/' + relative
+        // Recorded so the engine can check at the end of the cycle whether
+        // this file exists. It is the one thing this helper cannot answer for
+        // itself — it takes a path, not an entity, so there is nothing to look
+        // up and the URL is well-formed whether or not anything produced it.
+        track?.asset?.(destination)
         const from = path.dirname(entity.destination || '/')
         return { url: path.relative(from, destination) }
     }

package/src/plugins/render/resource.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-export function load({ runtime, entity, state, options }) {
+export function load({ runtime, entity, state, options, track }) {
     runtime.resource = (url) => {
         const { resourceLib } = state.resources
         for (let library in resourceLib) {
@@ -9,6 +9,10 @@ export function load({ runtime, entity, state, options }) {
                 const name = url.replace(origin, `${resourceLib[library]}`)
                 const relative = url.replace(origin, `${state.resources.resourcesFolder}/${resourceLib[library]}`)
                 const destination = '/' + relative
+                // Same reason as the asset helper: this builds a URL rather
+                // than resolving one, so a library that was never copied
+                // yields a link to nothing on a green build.
+                track?.asset?.(destination)
                 const from = path.dirname(entity.destination || '/')
                 return { url: path.relative(from, destination), name }
             }

package/src/report.js

@@ -115,6 +115,10 @@ export function resetReport() {
     runtime.state.renderErrors = []
     // Per cycle, unlike the wipe: what changed is a fact about THIS build.
     runtime.state.changed = { ids: [], count: 0 }
+    // Per cycle too: an asset referenced by a page that did not re-render this
+    // time was not re-checked, and claiming otherwise would be the kind of
+    // completeness this codebase keeps having to walk back.
+    runtime.state.assetUse = new Map()
 }
 
 // Published on the runtime so runtime.js can start a fresh cycle for a
@@ -209,6 +213,38 @@ export function reportEvaluated(scope, { evaluated, of } = {}) {
     store().evaluated[scope] = { evaluated: evaluated ?? 0, ...(Number.isFinite(of) ? { of } : {}) }
 }
 
+// Files a render linked to, and who linked to them.
+//
+// The URL helpers build paths rather than resolving them, so nothing they hand
+// a template has been checked against a file: a preset that never ran, or one
+// whose format changed under a template still naming the old extension,
+// produces a well-formed link to nothing. The page renders, the build is
+// green, and the image is missing until somebody looks at the site.
+//
+// Keyed by destination with the referencing entities attached, because "this
+// file is missing" is only actionable next to "and these pages point at it".
+//
+// NOT gated on reportWanted(): the check that reads this runs on every build,
+// and gating it would make a broken link visible only to someone who already
+// suspected one.
+export function reportAssetUse(destination, entityId) {
+    if (!destination) return
+    const store = assetUseStore()
+    if (!store.has(destination)) store.set(destination, new Set())
+    if (entityId) store.get(destination).add(entityId)
+}
+
+function assetUseStore() {
+    runtime.state ??= {}
+    runtime.state.assetUse ??= new Map()
+    return runtime.state.assetUse
+}
+
+// Everything referenced this cycle, as [destination, [entity ids]].
+export function assetUse() {
+    return [...assetUseStore()].map(([destination, ids]) => [destination, [...ids]])
+}
+
 // An entity whose SOURCE did not change is gated at import and never becomes
 // a render task at all — so it appears in neither `rendered` nor `skipped`,
 // and the two lists would not reconcile with the corpus size without saying

package/src/track.js

@@ -40,7 +40,7 @@ export function filterKey(filter) {
 // The returned object exposes `partials: Set<string>` and
 // `queries: Array<filter | null>` directly. Consumers iterate either
 // shape; both are owned by the track for the lifetime of the run.
-export function createTrack({ partial = true, query = true, lookup = true, meta = false, consumed = false } = {}) {
+export function createTrack({ partial = true, query = true, lookup = true, meta = false, consumed = false, assets = true } = {}) {
     const track = {}
     if (lookup) {
         // Lookups a TEMPLATE made by name: runtime.href('/contacts'),
@@ -122,6 +122,26 @@ export function createTrack({ partial = true, query = true, lookup = true, meta
             paths.add(path)
         }
     }
+    if (assets) {
+        // Files a template asked for by URL: a preset derivative, a resource
+        // from a library. Recorded so the engine can check at the end of the
+        // cycle whether the thing being linked to is actually in the output.
+        //
+        // The helpers BUILD these paths — nothing they return has been checked
+        // against a file — so a preset that never ran, or one whose format
+        // changed, produces a perfectly well-formed link to nothing. The page
+        // renders, the build is green, and the image is missing until a person
+        // notices.
+        //
+        // The output-relative destination, not the page-relative url the
+        // helper returns: `../../assets/web/hero.webp` cannot be resolved
+        // without knowing which page asked, and this is the form that maps
+        // straight onto a path under the output folder.
+        const assetRefs = new Set()
+        track.assets = assetRefs
+        track.asset = (destination) => { if (destination) assetRefs.add(destination) }
+    }
+
     if (query) {
         const queries = []
         const queryKeys = new Set()
@@ -282,6 +302,7 @@ export function serializeTrack(track) {
         partials:  track.partials  ? [...track.partials]  : undefined,
         queries:   track.queries   ? [...track.queries]   : undefined,
         metaReads: track.metaReads ? [...track.metaReads] : undefined,
+        assets:    track.assets    ? [...track.assets]    : undefined,
         lookups:   track.lookups   ? [...track.lookups].map(([k, v]) => [k, [...v]]) : undefined,
         consumedReads: track.consumedReads
             ? [...track.consumedReads].map(([k, v]) => [k, [...v]]) : undefined,
@@ -296,6 +317,7 @@ export function mergeTrack(target, data) {
     for (const p of data.partials  ?? []) target.partial?.(p)
     for (const q of data.queries   ?? []) target.query?.(q)
     for (const m of data.metaReads ?? []) target.metaRead?.(m)
+    for (const a of data.assets    ?? []) target.asset?.(a)
     for (const [name, ids] of data.lookups ?? []) target.lookup?.(name, ids)
     for (const [id, paths] of data.consumedReads ?? []) {
         for (const path of paths) target.consumedRead?.(id, path)