mikser-io 9.64.0 → 9.67.0

package/CLAUDE.md

@@ -233,6 +233,23 @@ brevity.
   - `{ name, options, postprocess, output?, setup?, teardown? }` →
     postprocessor descriptor; stored in `runtime.postprocessors`.
   Strings produce a v9 migration error pointing at the new shape.
+- `instance.js` — one engine per working folder. A second `mikser` in a
+  folder a watcher holds FORWARDS its build over a unix socket and wears
+  the instance's log output and exit code; `--no-attach` opts out and
+  warns. Socket lives in `os.tmpdir()` keyed by a hash of the resolved
+  working folder — NOT under `runtime/`, because sun_path caps a socket
+  path at ~107 bytes and a nested working folder fails as `listen
+  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. 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. 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`.
 - `manager.js` — file watching (chokidar) and cron scheduling. `watch()`
   turns file events into SYNC events — it is how a source folder becomes
   entities, so pointing it at the output folder feeds output back in as

package/app.js

@@ -1,8 +1,66 @@
 #!/usr/bin/env node
-import { setup } from "./index.js"
+import path from 'node:path'
+
+import { setup } from './index.js'
+import { forward } from './src/instance.js'
+
+// Before anything is imported or read.
+//
+// A second `mikser` in a folder a watcher already holds used to start a second
+// engine: two writers, one catalogue, one output tree, no warning. It forwards
+// the request instead and wears the answer — which also means it never pays to
+// import the config or the plugin graph, most of what a one-shot spends.
+//
+// Only the flags that decide WHERE are parsed here. Everything else is the
+// running instance's business, and parsing it properly is what commander is
+// for once we know we are staying.
+function locate(argv) {
+    const value = (...names) => {
+        for (const name of names) {
+            const i = argv.indexOf(name)
+            if (i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('-')) return argv[i + 1]
+            const inline = argv.find(a => a.startsWith(`${name}=`))
+            if (inline) return inline.slice(name.length + 1)
+        }
+        return null
+    }
+    const has = (...names) => names.some(n => argv.includes(n) || argv.some(a => names.some(x => a.startsWith(`${x}=`))))
+
+    // 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 {
+        workingFolder: value('--working-folder', '-i') ?? '.',
+        config: value('--config', '-c') ?? 'mikser.config.js',
+        // Commander's negated form: `attach` is true unless --no-attach said so.
+        attach: has('--no-attach') ? false : true,
+        request,
+    }
+}
 
 async function main() {
+    const where = locate(process.argv.slice(2))
+    if (where.attach !== false) {
+        const code = await forward({
+            workingFolder: path.resolve(where.workingFolder),
+            config: path.resolve(where.workingFolder, where.config),
+            request: where.request,
+        })
+        // null means nobody was listening — carry on exactly as before.
+        if (code !== null) process.exit(code)
+    }
+
     const mikser = await setup()
     await mikser.start()
 }
-main()
+main()

package/docs/diagnostics.md

@@ -27,6 +27,7 @@ engine source, the entry point is missing and belongs on this page.
 | Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
 | A tool answered emptily — is it broken, or is there nothing to find? | [`faults`](#faults) |
 | I edited the build and nothing rebuilt | `--json` → `config.files` |
+| Is another mikser already holding this folder? | run any command — it forwards, or says so |
 | Why did this build do any work at all? | `--json` → `invalidated` |
 | Did my new pattern get a chance to match? | `--json` → `evaluated` |
 
@@ -733,6 +734,44 @@ content is clean.
 get, stats, config }` — the on-demand render cache, useful for asking
 what has been rendered outside a build.
 
+## One engine per folder
+
+Running `mikser` while `mikser --watch` holds the same folder used to start a
+second engine: two writers over one catalogue and one output tree, with no lock
+and no warning. A `--clear` from either is what produces a cold rebuild that
+reports nothing rendered.
+
+A second invocation now forwards its build to the running instance and wears
+its answer — the instance's log output, the instance's exit code. Nothing to
+learn, and no question about *which* cycle covers your edit: you asked, so the
+answer is about your request. It is also faster, because a forwarded command
+never imports the config or the plugin graph, which is most of what a one-shot
+spends its time on.
+
+Three things it refuses or reports rather than guessing:
+
+- **A different config.** If you resolve `mikser.config.prod.js` and the
+  instance is running `mikser.config.js`, it refuses. Building with the wrong
+  config is the accident this exists to prevent.
+- **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 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
+request.
+
 ## Faults
 
 A **fault** is a subsystem saying it cannot do its job — as opposed to an

package/docs/rendering.md

@@ -113,6 +113,24 @@ Inside a render, a `runtime` object is assembled and passed to all plugins:
 
 Render plugins extend this object further (e.g. `runtime.href`, `runtime.asset`, `runtime.resource`).
 
+`asset(preset, url)` returns the deployed URL of a preset derivative, relative
+to the page asking for it:
+
+```hbs
+<img src="{{ (asset 'web' '/media/hero.jpg').url }}">
+```
+
+The extension comes from the preset — every preset module exports a `format`,
+and the helper uses it, so a template never has to repeat it. Pass a third
+argument to override it, and mikser warns if that contradicts what the preset
+actually produces.
+
+It BUILDS the url rather than looking one up, which is worth knowing: nothing
+it returns has been checked against a file. A preset name nothing declares
+warns once, but a derivative that simply was not generated cannot be detected
+here. Where you have the entity rather than a path, `meta.presets` is the
+looked-up answer (ADR-0011).
+
 ### Logging from templates
 
 The runtime exposes five logger functions — `log` (info), `warn`, `error`, `debug`, `trace` — that route through Mikser's central logger (`useLogger()` is resolved at call time, so progress-bar wrappers in `info` mode are honoured). Each renderer's auto-helper loop picks them up:

package/index.js

@@ -15,6 +15,9 @@ export * from './src/lifecycle.js'
 // cache's constraints: main-thread only, so async, so knex, so portable to
 // another engine.
 export * from './src/database/durable.js'
+// One engine per working folder: the control socket a second invocation
+// forwards to, and the guard that says so when it cannot.
+export * from './src/instance.js'
 
 export * from './src/database/index.js'
 export * from './src/journal.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.64.0",
+  "version": "9.67.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

@@ -6,6 +6,7 @@ import _ from 'lodash'
 import Piscina from 'piscina'
 import runtime from './runtime.js'
 import { onInitialize, onInitialized, onLoad, onImport, onRender, onCancel, onCancelled, onFinalized, onLoaded, onBeforePostprocess, onPostprocess, postprocessEntities } from './lifecycle.js'
+import { instanceControl } from './instance.js'
 import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
@@ -88,6 +89,127 @@ function workerSafeOptions(opts) {
     return result
 }
 
+// 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 = {
@@ -132,10 +254,16 @@ export async function setup(options) {
     // need an agent surface configured when `--verify` does not.
     registerBuiltinTools()
 
+    // One engine per working folder: publish the control socket when this
+    // process is long-running, and warn when a private one starts in a folder
+    // somebody else is already holding.
+    instanceControl()
+
     onInitialize(async () => {
         runtime.engine.commander?.version(packageInfo.version)
             .option('-i --working-folder <folder>', 'set mikser working folder', './')
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
+            .option('--no-attach', 'start a private engine instead of forwarding to the one already running here')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')
@@ -284,57 +412,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)
         }
     })
 
@@ -361,58 +440,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) => {

package/src/instance.js

@@ -0,0 +1,418 @@
+// One engine per working folder.
+//
+// Running `mikser` next to a live `mikser --watch` used to start a second
+// engine on the same folder: two writers, one sqlite catalogue, one output
+// tree, no lock and no warning. WAL keeps the pages intact and does nothing
+// for the logical state — a `--clear` from one process while the other holds
+// the folder produces a cold rebuild reporting nothing rendered, and output
+// that does not match source.
+//
+// The fix is not a lock alone, because a lock only forbids the thing people
+// were doing for a reason. A one-shot build is not faster than the watcher —
+// the watcher has usually already done the work — it is started because
+// PROCESS EXIT IS THE ONLY COMPLETION SIGNAL. Everything else in mikser
+// hot-reloads; nothing else says "the tree is settled, assert against it now".
+//
+// So a second invocation forwards its request to the running instance and
+// wears its result: the instance's log output, the instance's exit code. The
+// caller asked for a build and gets an answer about that build, with nothing
+// new to learn and no watermark to reason about — which matters, because a
+// design that needs discipline from the caller is the one that gets violated.
+//
+// `--no-attach` opts out, for when a fresh process IS the point: checking that
+// a cold start works, that startup ordering hides nothing. Named for what it
+// switches off rather than for a property of the process — the default is to
+// attach, and the flag should say which behaviour is being declined.
+
+import net from 'node:net'
+import { createHash } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { existsSync, unlinkSync } from 'node:fs'
+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.
+//
+// A unix socket rather than a port: no allocation, no auth decision, no
+// network exposure. The obvious home is under the working folder, and it does
+// not work — sun_path caps a socket path at about 107 bytes, and a working
+// folder nested a few levels deep blows through that. It fails as
+// `listen EINVAL`, which is not a phrase that suggests "your path is long",
+// so it would have been diagnosed as forwarding simply not working.
+//
+// So: a short, fixed-length name in the system temp directory, derived from
+// the resolved working folder. One rule, no length to exceed, and it survives
+// an `rm -rf runtime`.
+//
+// The permissions argument survives the move. The socket is chmod 0600 after
+// listen, so it is the owner's alone — /tmp being world-writable buys an
+// attacker the ability to create their own socket, not to talk to this one.
+//
+// Windows has no unix sockets; Node maps this name shape onto a named pipe,
+// which has no such length limit.
+export function socketPath(workingFolder) {
+    const key = createHash('sha1').update(path.resolve(workingFolder ?? '.')).digest('hex').slice(0, 16)
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\mikser-${key}`
+        : path.join(tmpdir(), `mikser-${key}.sock`)
+}
+
+// ── protocol ────────────────────────────────────────────────────────────
+//
+// 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: 'report', config, tool, tools, toolArgs, explain, verify, json }
+//   ← { type: 'log', chunk }        (zero or more, in order)
+//   ← { type: 'done', code }
+//   ← { type: 'refused', reason, detail }
+
+function frame(socket, object) {
+    try { socket.write(JSON.stringify(object) + '\n') } catch { /* peer gone */ }
+}
+
+function readFrames(socket, onFrame) {
+    let buffer = ''
+    socket.on('data', (chunk) => {
+        buffer += chunk.toString()
+        let index
+        while ((index = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, index)
+            buffer = buffer.slice(index + 1)
+            if (!line.trim()) continue
+            try { onFrame(JSON.parse(line)) } catch { /* not ours */ }
+        }
+    })
+}
+
+// ── client ──────────────────────────────────────────────────────────────
+
+// Ask the running instance to build, and wear its answer.
+//
+// Returns the exit code to use, or null when there is nobody to ask — in
+// 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, request }) {
+    const endpoint = socketPath(workingFolder)
+
+    return new Promise((resolve) => {
+        const socket = net.connect(endpoint)
+        let answered = false
+
+        // Nobody home. A crash leaves the socket file behind, so "connect
+        // failed" has to mean "no instance — clean up and carry on" rather
+        // than a hang: this is the way the pattern usually breaks.
+        socket.on('error', () => {
+            if (answered) return
+            answered = true
+            if (process.platform !== 'win32' && existsSync(endpoint)) {
+                try { unlinkSync(endpoint) } catch { /* another client won the race */ }
+            }
+            resolve(null)
+        })
+
+        socket.on('connect', () => frame(socket, { ...request, config }))
+
+        readFrames(socket, (message) => {
+            if (message.type === 'log') {
+                // The instance's output for THIS request, on the stream it
+                // would have used locally.
+                process.stderr.write(message.chunk)
+            } else if (message.type === 'refused') {
+                answered = true
+                process.stderr.write(`mikser: ${message.reason}\n`)
+                if (message.detail) process.stderr.write(`${message.detail}\n`)
+                socket.end()
+                resolve(1)
+            } else if (message.type === 'done') {
+                answered = true
+                socket.end()
+                resolve(message.code ?? 0)
+            }
+        })
+
+        // The instance went away mid-request. Not "success with no output":
+        // the build this was asked about has no known outcome.
+        socket.on('close', () => {
+            if (answered) return
+            answered = true
+            process.stderr.write('mikser: the running instance closed the connection before finishing.\n')
+            resolve(1)
+        })
+    })
+}
+
+// ── server ──────────────────────────────────────────────────────────────
+
+// Requests run one at a time, to completion.
+//
+// Not because the engine could not interleave them, but because "which cycle
+// covers my edit" is the question this whole thing exists to remove. Serialised,
+// a client's answer is about a cycle that started after its request arrived,
+// and the log output during that window belongs to exactly one request.
+let chain = Promise.resolve()
+let server = null
+
+// Tee the process's own output to the client for the duration of its request.
+//
+// The engine logs through pino to stdout/stderr; capturing there rather than
+// adding a log transport means the client sees precisely what it would have
+// seen locally, formatting and all, with no second rendering of the same
+// records to keep in step.
+function captureOutput(onChunk) {
+    const originals = [process.stdout.write, process.stderr.write]
+    const patch = (stream, original) => function (chunk, encoding, callback) {
+        try { onChunk(typeof chunk === 'string' ? chunk : chunk.toString()) } catch { /* client gone */ }
+        return original.call(stream, chunk, encoding, callback)
+    }
+    process.stdout.write = patch(process.stdout, originals[0])
+    process.stderr.write = patch(process.stderr, originals[1])
+    return () => {
+        process.stdout.write = originals[0]
+        process.stderr.write = originals[1]
+    }
+}
+
+// Is the config the client resolved the one this instance is running?
+//
+// The accident this prevents is the one already written down: a command
+// resolving mikser.config.prod.js reaching an instance running the dev config
+// executes against the wrong one, silently. Compared by resolved PATH rather
+// than by content hash — the hash would require the client to import its
+// config, which is most of the startup forwarding exists to skip, and it is
+// not what tells the two apart. Different configs are different files.
+function configMismatch(theirs) {
+    if (!theirs) return null
+    const mine = path.resolve(runtime.options.config ?? 'mikser.config.js')
+    return path.resolve(theirs) === mine ? null : mine
+}
+
+// Has this instance's own config changed under it since it started?
+//
+// The other half of the same question, and the half a client cannot answer.
+// configCoverage lists every local module the config graph pulled in, so a
+// stat over that list catches an edit to an imported module — which a
+// client-side checksum of the entry file would miss entirely.
+async function configStale() {
+    const covered = runtime.options.configCoverage?.files ?? []
+    if (!covered.length) return null
+    const { stat } = await import('node:fs/promises')
+    const stamps = runtime.options.configStamps
+    if (!stamps) {
+        // First call: record, do not judge. Nothing to compare against yet.
+        runtime.options.configStamps = Object.fromEntries(
+            await Promise.all(covered.map(async (file) => {
+                try { return [file, (await stat(file)).mtimeMs] } catch { return [file, 0] }
+            })))
+        return null
+    }
+    for (const file of covered) {
+        let now = 0
+        try { now = (await stat(file)).mtimeMs } catch { /* deleted counts as changed */ }
+        if (stamps[file] !== now) return file
+    }
+    return null
+}
+
+// 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 })
+}
+
+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 {
+        // Fire the pending debounce rather than waiting it out.
+        //
+        // The 1000ms window exists to INFER that editing has stopped. A client
+        // asking for a build has STATED it, so inference is not needed and the
+        // timer is pure latency. The accumulated events are not discarded by
+        // this: the watcher already wrote them into the journal, so clearing
+        // the timer and building now covers exactly what it would have.
+        clearTimeout(runtime.engine?.processTimeout)
+
+        // RESCAN, not drain.
+        //
+        // A watch cycle processes what the watcher reported. A client that
+        // writes a file and immediately asks for a build can beat the inotify
+        // event, so draining what is already queued would build without the
+        // change that prompted the request — the watermark bug wearing a
+        // different hat. Rescanning makes a forwarded build mean what a
+        // one-shot means, which is what every existing caller assumes.
+        await runtime.rebuild()
+
+        // From the render-error count, NOT from process.exitCode.
+        //
+        // The engine deliberately leaves exitCode alone in watch mode — a
+        // failed render there is a state to fix on the next cycle, not a
+        // reason to tear the watcher down — and the instance is always in
+        // watch or server mode. So the signal a one-shot would have exited
+        // with does not exist here and has to be read from the report, which
+        // is where it came from in the first place.
+        code = renderErrorCount() ? 1 : 0
+    } catch (err) {
+        logger?.error('instance: forwarded build failed — %s', err.message)
+        code = 1
+    } finally {
+        restore()
+    }
+    frame(socket, { type: 'done', code })
+}
+
+// Listen, if this process is one that sticks around.
+//
+// A one-shot build has nothing to offer a client — it is already exiting — so
+// only a watcher or a server publishes an endpoint.
+export function serveInstance() {
+    onLoaded(async () => {
+        if (!runtime.options.watch && !runtime.options.server) return
+        if (runtime.options.attach === false) return
+        const logger = runtime.engine?.logger
+        const endpoint = socketPath(runtime.options.workingFolder)
+
+        // A socket left by a crash. Nothing is listening, so removing it is
+        // safe — and a live one would have refused this process's own startup
+        // long before here, in the client check.
+        if (process.platform !== 'win32' && existsSync(endpoint)) {
+            try { unlinkSync(endpoint) } catch { /* nothing to remove */ }
+        }
+        await configStale()   // record the baseline stamps
+
+        server = net.createServer((socket) => {
+            socket.on('error', () => { /* client vanished mid-request */ })
+            readFrames(socket, (request) => {
+                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) => {
+            logger?.warn({ code: 'instance-listen-failed' },
+                'Could not open the control socket (%s). Other mikser commands in this folder will start their '
+                + 'own engine instead of talking to this one.', err.message)
+        })
+        server.listen(endpoint, async () => {
+            // The owner's, and nobody else's — the filesystem permission IS
+            // the access decision, which is why this needs no token.
+            if (process.platform !== 'win32') {
+                try { await chmod(endpoint, 0o600) } catch { /* best effort */ }
+            }
+            logger?.info('Instance socket: %s', endpoint)
+        })
+        server.unref?.()
+
+        const close = () => {
+            try { server?.close() } catch { /* already closed */ }
+            if (process.platform !== 'win32' && existsSync(endpoint)) {
+                try { unlinkSync(endpoint) } catch { /* gone */ }
+            }
+        }
+        process.on('exit', close)
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            process.on(signal, () => { close(); process.exit(0) })
+        }
+    })
+}
+
+// Say so when a private engine is starting in a folder someone else holds.
+//
+// The local counterpart of the rule already written down for deployments —
+// "never run a one-shot mikser command against the deployment" — which existed
+// because there was no alternative. There is one now, so this covers what is
+// left: --no-attach, and the report-only runs that stay local by design.
+//
+// A warning rather than a refusal. --no-attach is how you deliberately check
+// that a cold start works, and refusing it would take away the escape hatch
+// this design depends on having.
+export async function warnIfHeld({ workingFolder, attached }) {
+    const endpoint = socketPath(workingFolder)
+    if (process.platform !== 'win32' && !existsSync(endpoint)) return false
+
+    const live = await new Promise((resolve) => {
+        const probe = net.connect(endpoint)
+        const done = (answer) => { try { probe.destroy() } catch { /* already gone */ } resolve(answer) }
+        probe.on('connect', () => done(true))
+        probe.on('error', () => done(false))
+        setTimeout(() => done(false), 250).unref?.()
+    })
+    if (!live) return false
+
+    const logger = runtime.engine?.logger
+    const message = attached === false
+        ? 'Another mikser is already running in this folder, and --no-attach means this one will not talk to '
+          + 'it. Two engines share the catalogue and the output tree with no lock between them; a --clear from '
+          + 'either is what produces a cold rebuild that renders nothing.'
+        : 'Another mikser is already running in this folder. This command reads and does not write, so it is '
+          + 'safe — but it may see a catalogue mid-cycle.'
+    logger?.warn?.({ code: 'instance-already-running' }, message)
+    return true
+}
+
+// Registered at setup so both halves are wired from one call.
+export function instanceControl() {
+    serveInstance()
+    onLoaded(async () => {
+        if (runtime.options.watch || runtime.options.server) return
+        await warnIfHeld({
+            workingFolder: runtime.options.workingFolder,
+            attached: runtime.options.attach,
+        })
+    })
+}

package/src/plugins/render/asset.js

@@ -1,9 +1,61 @@
 import path from 'node:path'
 
-export function load({ runtime, entity, state, options }) {
+import { changeExtension } from '../../utils.js'
+
+// `{{asset 'web' '/media/hero.jpg'}}` — the deployed URL of a preset
+// derivative, relative to the page asking for it.
+//
+// It BUILDS the URL rather than looking one up, which is the source of every
+// way it used to go wrong: nothing it returns has been checked against
+// anything, so a mistake produces a perfectly well-formed link to a file that
+// does not exist. The page renders, the build is green, and the image is
+// missing — noticed by a person, later.
+//
+// Three of those are closed here. The remaining one is structural: the
+// 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 }) {
+    const presets = state?.assets?.presets ?? {}
+    const warned = new Set()
+    const warnOnce = (key, code, message, ...args) => {
+        if (warned.has(key)) return
+        warned.add(key)
+        logger?.warn?.({ code }, message, ...args)
+    }
+
     runtime.asset = (preset, url, format) => {
         if (url[0] != '/') url = `/${url}`
-        const relative = `${state.assets.assetsFolder}/${preset}${format ? url.split('.').slice(0, -1).concat(format).join('.') : url}`
+
+        const declared = presets[preset]?.format
+
+        // A preset name nothing declares. The URL still gets built — it is a
+        // string operation and cannot fail — so without this a typo is a
+        // missing image and no other symptom anywhere.
+        if (!presets[preset]) {
+            warnOnce(`preset:${preset}`, 'asset-unknown-preset',
+                'asset() was asked for preset %j, which is not configured. The URL it returns points at a '
+                + 'derivative nothing generates. Configured: %s',
+                preset, Object.keys(presets).sort().join(', ') || '(none)')
+        }
+
+        // The format the preset itself declares, unless the caller overrode
+        // it. Every preset module exports one, so requiring the template to
+        // repeat it made the extension a thing two places had to agree about
+        // — and when they disagreed the link was wrong with nothing said.
+        const effective = format ?? declared
+
+        if (format && declared && format !== declared) {
+            warnOnce(`format:${preset}:${format}`, 'asset-format-mismatch',
+                'asset() was given format %j for preset %j, which produces %j. One of the two is wrong and '
+                + 'the URL follows the argument.', format, preset, declared)
+        }
+
+        // changeExtension, not a local split-and-rejoin. The inline version
+        // returned "webp" for a source with no extension — dropping the path
+        // and yielding a relative URL that resolves against whatever page
+        // happened to be rendering.
+        const relative = `${state.assets.assetsFolder}/${preset}${effective ? changeExtension(url, effective) : url}`
         const destination = '/' + relative
         const from = path.dirname(entity.destination || '/')
         return { url: path.relative(from, destination) }

package/src/report.js

@@ -117,6 +117,11 @@ export function resetReport() {
     runtime.state.changed = { ids: [], count: 0 }
 }
 
+// Published on the runtime so runtime.js can start a fresh cycle for a
+// forwarded build without importing this module — runtime.js loads first, and
+// an import here would close the cycle.
+runtime.resetReport = resetReport
+
 // End of a cycle: stamp it, file it, and wake anyone waiting on it.
 export function finishCycle() {
     if (!runtime.state?.cycle || runtime.state.cycle.finishedAt) return

package/src/runtime.js

@@ -111,6 +111,25 @@ const runtime = {
         if (!this.options?.watch && !this.options?.server) await this.closeDurable?.()
     },
 
+    // A build on request, from a process that is already running.
+    //
+    // start() runs the import hooks once and every cycle after that only
+    // processes what the watcher reported. A forwarded build has to RESCAN:
+    // a client that writes a file and immediately asks can beat the inotify
+    // event, and draining the queue would then build without the change that
+    // prompted the request. Scanning makes it mean what a one-shot means.
+    //
+    // The gate makes the rescan cheap — an unchanged file is a checksum
+    // comparison, not a re-import.
+    async rebuild() {
+        // Its own cycle in the report, like any other — otherwise a forwarded
+        // build's counts are added to whatever the watcher last did.
+        this.resetReport?.()
+        await this.callHooks(this.hooks.import, undefined, 'import')
+        await this.callHooks(this.hooks.imported, undefined, 'imported')
+        await this.process()
+    },
+
     async process() {
         if (this.abortController?.signal.aborted) return
         else if (this.abortController) {