mikser-io 10.3.0 → 10.5.0

package/app.js

@@ -54,11 +54,11 @@ function locate(argv) {
     // 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('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json') }
-        : has('--fingerprint')    ? { type: 'report', fingerprint: true, json: has('--json') }
+    const request = has('--tools') ? { type: 'report', tools: true, json: has('--json'), log: value('--log') ?? value('-l') }
+        : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json'), log: value('--log') ?? value('-l') }
+        : explain                 ? { type: 'report', explain, json: has('--json'), log: value('--log') ?? value('-l') }
+        : has('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json'), log: value('--log') ?? value('-l') }
+        : has('--fingerprint')    ? { type: 'report', fingerprint: true, json: has('--json'), log: value('--log') ?? value('-l') }
         : { type: 'build',
             clear: has('--clear'),
             // Not a flag that happens to be set — the client's OUTPUT
@@ -74,7 +74,16 @@ function locate(argv) {
             // rebuilt whatever the gates let through, which on a settled tree
             // is nothing, and a caller asking for a full re-render got a no-op
             // reported as success.
-            force: has('--force', '-f') }
+            force: has('--force', '-f'),
+            // The level travels for the same reason --json does: it is an
+            // OUTPUT CONTRACT, and the process doing the writing is the
+            // instance, which was started without it. A forwarded --log
+            // otherwise changed the level of a process that prints nothing.
+            log: value('--log') ?? value('-l'),
+            // Instance state rather than a contract: these outlive the request
+            // on purpose, which is the case a per-request flag cannot serve.
+            logInstall: value('--log-install'),
+            logReset: has('--log-reset') }
 
     return {
         longRunning,

package/docs/configuration.md

@@ -54,8 +54,9 @@ These options are part of `runtime.options` and apply to the engine itself.
 | `force` | `-f, --force` | boolean | `false` | Rebuild everything; disable incremental dispatch. |
 | `resume` | `-R, --resume` | boolean | `false` | Continue from journal entries left by a previous interrupted run; skip the initial filesystem scan. The journal table survives crashes, so an interrupted cycle can be picked up by re-running with `--resume`. |
 | `verify` | `--audit-output` | boolean | `false` | Verify the output folder against the manifest snapshot — report drift instead of building. |
-| `debug` | `-d, --debug` | boolean | `false` | Enable debug-level logging. |
-| `trace` | `-t, --trace` | boolean | `false` | Enable trace-level logging (very verbose). |
+| `log` | `-l, --log` | string | — | Log level for this run: `trace`, `debug`, `info`, `notice`, `warn`, `error`, `fatal`, `silent`. Replaces the old `--debug` / `--trace` booleans, which could not express "warnings only" and, in `--debug`'s case, did nothing at all — it moved the logger's level while the terminal stream kept the one it was built with. |
+| `logInstall` | `--log-install` | string | — | Set the level on a **running** instance, so its own rebuilds are verbose too — the case a per-request flag cannot serve. Expires after 30 minutes, dies with the process, and is disclosed in the build report under `logLevel`. |
+| `logReset` | `--log-reset` | boolean | `false` | Return a running instance to its configured level. |
 | `threads` | — | number | `4` | Worker thread count for the Piscina pools (`renderWorkers`, `postprocessWorkers`). Both pools are lazy (`minThreads: 0` + `idleTimeout: 30_000`) so INLINE-only workloads spin up zero workers. |
 | `server` | `-s, --server [port]` | number\|boolean | — | When set, the engine creates a shared Express app on `runtime.options.app` and listens on the given port (default `3001`) after all plugins have mounted their routes. Plugins like `api` attach to it instead of starting their own server. The `outputFolder` is also served as a static catch-all route at `/` (plugin routes match first; anything that doesn't match falls through to the rendered output). Requires `express` to be installed. |
 | `junk` | — | array\|false | built-in list | OS and file-manager litter, filtered out of both the scan and the watcher. The dot-prefixed files (`.DS_Store`, `._*`) were already invisible — globby defaults to `dot: false` and the watcher ignores leading dots — but the Windows ones are **not** dotfiles: `Thumbs.db` and `desktop.ini` were measurably scanned *and* watched, and became entities. The list is deliberately conservative (OS/file-manager artifacts and application lock files only, no `*.tmp`, `*.bak` or editor backups), because a filter that silently drops content is worse than the litter it prevents. `false` disables it; an array replaces it. See `isJunkPath` / `JUNK_IGNORE` in `src/utils.js`. Plugins that write metadata next to content add their own patterns with `registerJunk({ ignore, match })` — the engine provides the mechanism and the plugin the knowledge of what its files are called (`mikser-io-drive` registers `*.nephelemeta`). Plugin registrations survive an array override, since narrowing the OS list is not a request to start importing a library's sidecars. |
@@ -360,24 +361,128 @@ export default {
 
 ### `commands`
 
+Runs shell commands at lifecycle hooks. A plugin, so it goes in `plugins` and
+takes its options as factory arguments:
+
 ```js
+import { commands } from 'mikser-io'
+
 export default {
-  commands: {
-    // Run shell commands at any lifecycle hook
-    load: 'echo Loading...',
-    finalized: ['npm run compress', 'npm run deploy'],
-
-    // Commands can also be async functions
-    processed: async (runtime) => {
-      if (runtime.options.mode === 'production') {
-        return 'npm run optimize'
-      }
-    }
-  }
+  plugins: [
+    commands({
+      load: 'echo Loading...',
+      finalized: ['npm run compress', 'npm run deploy'],
+      // Also an async function, resolved when the hook fires
+      processed: async () => process.env.NODE_ENV === 'production' && 'npm run optimize',
+    }),
+  ],
 }
 ```
 
-Available hook names: `load`, `loaded`, `import`, `imported`, `process`, `processed`, `persist`, `persisted`, `beforeRender`, `render`, `afterRender`, `cancel`, `cancelled`, `finalize`, `finalized`.
+Hook names: `load`, `loaded`, `import`, `imported`, `process`, `processed`,
+`persist`, `persisted`, `beforeRender`, `render`, `afterRender`, `cancel`,
+`cancelled`, `finalize`, `finalized`.
+
+#### From the command line
+
+One flag names a hook, so a one-off side effect needs no config edit:
+
+```bash
+mikser --command finalized="node deploy/publish.mjs"
+
+# repeatable
+mikser --command loaded="node probe.mjs" --command finalized="node publish.mjs"
+```
+
+The same shape as `--tool <name>`: one word of CLI namespace for an
+open-ended set, rather than one flag per hook. It runs *in addition to*
+whatever the config declares for that hook, and only for that run. Forwarded
+to a running `--watch` instance it **replaces** the previous request's
+commands rather than adding to them, and the instance's own rebuilds run
+none — one hook is registered at load and reads a value the instance swaps
+per request. The flag exists only when `commands()` is in the config, like
+every plugin option, and an unknown hook name is refused before anything is
+built.
+
+#### Installing on a running instance
+
+`--command` spends itself on one build. A watcher's **own** rebuilds — the
+ones a file save triggers, which is the point of watching — run nothing, so a
+probe fires only when you forward a build by hand. `--command-install` puts it
+on the instance instead:
+
+```bash
+mikser --command-install finalized="node probe.mjs"   # installs, and runs now
+# ...edit a file, the watcher rebuilds  → probe runs
+# ...edit again                         → probe runs
+mikser --command-reset                                # clears all of them
+mikser --command-reset finalized                      # or just one hook
+```
+
+Installed commands are announced on **every** cycle, not once — you may have
+set one an hour ago, and each build's report has to carry the fact that it was
+not a function of the repository alone. Per-request commands are announced
+once per process, because they are in the invocation you just typed.
+
+On a one-shot build there is no instance to install on, so `--command-install`
+runs once and exits with the process exactly like `--command` — reported under
+`command-install-without-instance` rather than left to look persistent.
+
+To see what is attached, read the last build: every installed command is
+announced on **every** cycle under `command-from-cli`, so the log or the
+`--json` report names each one. There is deliberately no `--tool commands` —
+the tool registry is mirrored into MCP over HTTP with an allow-all default,
+and a command string routinely carries a path, a host or a token. Listing
+them there would hand an authenticated web client a map of the build box, and
+tools have no per-tool scope to gate it with.
+
+Two hooks behave differently from the rest, and both say so rather than
+failing quietly:
+
+- **`load` is refused.** Options are declared *during* the load phase and the
+  table is parsed after it, so a `--command load=` could never fire. It is
+  named and refused rather than left out of the list, because "no hook named
+  load" would be untrue and would send you looking for a typo. Declare it in
+  the config instead.
+- **`loaded` does not fire for a forwarded build.** A running instance loaded
+  at startup and a rebuild does not repeat the load phase, so a load-phase
+  hook belongs to the instance rather than to the request. Asking for one
+  warns under `command-hook-not-reached`. Stop the instance, or use a
+  per-cycle hook.
+
+Two hooks behave differently from the rest, and both say so rather than
+failing quietly:
+
+- **`load` is refused.** Options are declared *during* the load phase and the
+  table is parsed after it, so a `--command load=` could never fire. Declare
+  it in the config instead.
+- **`loaded` does not fire for a forwarded build.** A running instance loaded
+  at startup and a rebuild does not repeat the load phase, so a load-phase
+  hook belongs to the instance rather than to the request. Asking for one
+  warns under `command-hook-not-reached`. Stop the instance, or use a
+  per-cycle hook.
+
+Two things to know, and they are the reason this is a flag rather than a
+convenience:
+
+**It is reported, under `command-from-cli`.** A build is otherwise a function
+of the repository — same commit, same bytes, and `--fingerprint` can prove it.
+A command from argv makes it a function of the repo *and* how it was invoked,
+so an agent, a person and CI can all run "the same build" and get different
+output. The warning carries the hook and the command string into `--json`
+`warnings`, so a fingerprint taken from that build stays interpretable instead
+of quietly meaning something else.
+
+**A command that writes into the output folder fails `--audit-output`.** Not a
+limitation to work around — mikser hashes each file as it writes it, so
+rewriting one afterwards is indistinguishable from tampering, and the audit
+reports it as `Mismatched` and exits 2. Post-build minification through a hook
+is therefore the wrong shape; it belongs in a renderer or a postprocessor,
+where the hash is taken over what is actually deployed. The honest use for
+hooks is side effects that do not touch `out/` — publishing, notifying,
+syncing — which is also the case where a flag beats config, because deploy
+steps are environment-specific and do not belong in a repository's build
+config.
 
 ### `shares`
 

package/docs/diagnostics.md

@@ -328,7 +328,7 @@ compare against. It never appears alongside `matched` or `dependency`
 either: a consumer switches on `reason` and reads one field, so a stray
 key from another branch would make that switch wrong.
 
-The same detail appears at `--debug` for a watch run, one line per render.
+The same detail appears at `--log debug` for a watch run, one line per render.
 It is deliberately not in the build's normal output — the counts are the
 summary and `--json` is the record — but when you are watching one page
 misbehave, the trigger is the point.
@@ -419,7 +419,9 @@ thing `find out -type f` cannot do.
 | `-f, --force` | ignore all three gates (import checksum, dispatch, manifest) and re-render everything |
 | `-R, --resume` | continue from a previous interrupted run's journal; skips the filesystem scan |
 | `-r, --clear` | clear state before running |
-| `-d, --debug` / `-t, --trace` | raise log level; `trace` includes per-entity catalog writes |
+| `-l, --log <level>` | set the level for this run; `trace` includes per-entity catalog writes |
+| `--log-install <level>` | raise the level on a RUNNING instance without restarting it — restarting drops every connected MCP and drive session, so the tool you need should not require the risky act you are diagnosing. Expires after 30 minutes, dies with the process, and appears in the build report under `logLevel` so a level left on production is findable. |
+| `--log-reset` | put a running instance back to its configured level |
 | `--tools` | list the registered tools, then exit; `--json` for full schemas |
 | `--tool <name>` | run one tool and print its result, then exit. `--tool-args '<json>'` supplies arguments |
 

package/docs/getting-started.md

@@ -114,8 +114,11 @@ mikser [options]
                                    interrupted run; skip the initial filesystem scan
       --audit-output                     Audit output against recorded snapshots; report
                                    drift instead of building
-  -d, --debug                      Show debug log statements
-  -t, --trace                      Show trace log statements
+  -l, --log <level>                Log level for this run: trace, debug, info,
+                                   notice, warn, error, fatal, silent
+  --log-install <level>            Set the level on a RUNNING instance, so its
+                                   own rebuilds are verbose too. Expires.
+  --log-reset                      Return an instance to its configured level
   -e, --runtime-folder <folder>    Runtime/temp folder (default: runtime)
 ```
 

package/docs/lifecycle.md

@@ -91,7 +91,7 @@ onInitialized(async () => {
 
 **What Mikser does here:**
 - Parses CLI arguments and merges into `runtime.options`
-- Sets logger level based on `--debug` / `--trace` flags
+- Sets the logger level from `--log <level>`, moving the terminal stream with it
 - Resolves absolute paths for `workingFolder`, `outputFolder`, `runtimeFolder`
 - Creates the `runtimeFolder` directory
 - Clears `outputFolder` and `runtimeFolder` if `--clear` was set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "10.3.0",
+  "version": "10.5.0",
   "files": [
     "app.js",
     "index.js",

package/src/cli.js

@@ -46,7 +46,13 @@ const declared = new Map()
 // is being built is always undefined. Read it in a hook: onLoaded and later
 // all run after stage two. documents() read its folder at construction first,
 // and `--documents content` silently did nothing.
-export function cliOption(flags, description, defaultValue) {
+// `parseArg` and `defaultValue` mirror commander's own signature, so a plugin
+// that wants a REPEATABLE option can pass a collector — which is what a flag
+// naming one of several things needs, and what `--command hook=cmd` is. Kept
+// commander-compatible rather than inventing a shape: the third argument is a
+// coercion function when it is callable and a default otherwise, which is
+// exactly how commander reads it.
+export function cliOption(flags, description, parseArg, defaultValue) {
     // No CLI at all — a plugin constructed by a test harness, or embedded
     // programmatically through setup({ ... }) rather than run from a terminal.
     // There is nothing to register the option on and nothing about that is a
@@ -65,11 +71,20 @@ export function cliOption(flags, description, defaultValue) {
             + 'Declare options while the plugin is constructed (the load phase), not afterwards — '
             + 'a later one would never be read and the flag would look ignored.')
     }
-    if (declared.has(flags)) return declared.get(flags)
-    const option = defaultValue === undefined
+    if (declared.has(flags)) return declared.get(flags).option
+    const coerce = typeof parseArg === 'function' ? parseArg : undefined
+    const fallback = coerce ? defaultValue : parseArg
+    const option = coerce
+        ? commander.option(flags, description, coerce, fallback)
+        : fallback === undefined
         ? commander.option(flags, description)
-        : commander.option(flags, description, defaultValue)
-    declared.set(flags, option)
+        : commander.option(flags, description, fallback)
+    // The coercion is remembered, not just applied. pluginOptionsFrom rebuilds
+    // a throwaway parser to read a forwarded client's argv, and a collector
+    // left out there would hand back the last value where the local run got an
+    // array — the forwarded path quietly behaving differently from the local
+    // one, which is the failure the instance surface exists to remove.
+    declared.set(flags, { option, coerce, fallback })
     return option
 }
 
@@ -154,7 +169,11 @@ export function pluginOptionsFrom(argv) {
     let parsed
     try {
         const probe = commander.createCommand()
-        for (const flags of declared.keys()) probe.option(flags, '')
+        for (const [flags, { coerce, fallback }] of declared) {
+            if (coerce) probe.option(flags, '', coerce, fallback)
+            else if (fallback === undefined) probe.option(flags, '')
+            else probe.option(flags, '', fallback)
+        }
         probe.allowUnknownOption(true).allowExcessArguments(true)
         probe.parse(argv, { from: 'user' })
         parsed = probe.opts()

package/src/engine.js

@@ -24,7 +24,10 @@ import map from 'p-map'
 import Queue from 'p-queue'
 import packageInfo from '../package.json' with { type: 'json' }
 import { attachServerCliOptions, setupServer } from './server.js'
-import { createMikserLogger } from './logger.js'
+import {
+    createMikserLogger, setLogLevel, rememberBaseLevel, installLogLevel, resetLogLevel,
+    applyInstalledLogLevel, installedLogLevel, LOG_LEVELS, INSTALLED_LOG_TTL_MS,
+} from './logger.js'
 import { inputHashOf } from './utils.js'
 import { createTrack, mergeTrack } from './track.js'
 import { queryContext } from './database/query-context.js'
@@ -552,8 +555,19 @@ export async function setup(options) {
             .option('--fingerprint', 'hash everything this build wrote — including what it wrote through a '
                 + 'symlink, which `find` does not descend into — and exit. One comparable number per output '
                 + 'tree, plus one per asset preset, for proving an upgrade moved no bytes.', false)
-            .option('-d --debug', 'display debug statements')
-            .option('-t --trace', 'display trace statements')
+            // One level, not two booleans.
+            //
+            // `--debug` and `--trace` could not say "warnings only on this
+            // build" or "trace this one thing", and --debug did not work at
+            // all: it moved the logger's level while the terminal stream kept
+            // the one it was built with, so debug records were accepted and
+            // discarded. Both are gone rather than aliased — a flag that lies
+            // is worse than a flag that is missing.
+            .option('-l --log <level>', `log level for this run: ${LOG_LEVELS.join(', ')}`)
+            .option('--log-install <level>', 'set the log level on a RUNNING instance, so its own '
+                + `rebuilds are verbose too. Expires after ${INSTALLED_LOG_TTL_MS / 60000} minutes and `
+                + 'dies with the process. Levels as above.')
+            .option('--log-reset', 'return a running instance to its configured log level', false)
             .option('-e --runtime-folder <folder>', 'set mikser runtime folder relative to working folder', 'runtime')
         attachServerCliOptions(runtime.engine.commander)
 
@@ -666,16 +680,20 @@ The full version, with what each code means: docs/diagnostics.md`)
         // runtime.options.info gates the progress bar — gauge stays
         // silent in --debug/--trace modes because logs are voluminous
         // there and a bar on top would just be noise.
+        //
+        // Applied through setLogLevel so the terminal STREAM moves with the
+        // logger — the whole reason --debug did nothing.
         runtime.options.info = true
-        if (runtime.options.debug) {
-            runtime.engine.logger.level = 'debug'
-            runtime.options.info = false
-        }
-        if (runtime.options.trace) {
-            runtime.engine.logger.level = 'trace'
-            runtime.options.debug = false
-            runtime.options.info = false
+        const asked = runtime.options.log
+        if (asked) {
+            if (!LOG_LEVELS.includes(asked)) {
+                throw new Error(`--log ${asked}: no such level. Levels: ${LOG_LEVELS.join(', ')}`)
+            }
+            setLogLevel(asked)
+            // A bar on top of debug output is noise, and silent means silent.
+            if (asked === 'trace' || asked === 'debug' || asked === 'silent') runtime.options.info = false
         }
+        rememberBaseLevel(asked && LOG_LEVELS.includes(asked) ? asked : 'info')
 
         // Resolve folders inside onInitialize so journal.js and
         // catalog.js (which initialize in onInitialized) see absolute

package/src/instance.js

@@ -37,6 +37,9 @@ import runtime from './runtime.js'
 import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
 import { runReportOnly } from './engine.js'
+import {
+    setLogLevel, installLogLevel, resetLogLevel, restingLogLevel,
+} from './logger.js'
 import { emitReport } from './report.js'
 import { pluginOptionsFrom } from './cli.js'
 
@@ -418,6 +421,17 @@ async function withRequestOutput(request, run) {
     // Set for the duration of the request and restored with the rest, so a
     // watcher's own cycle before or after is unaffected.
     request = { ...request, requested: true }
+
+    // The level the CLIENT asked for, for this request only.
+    //
+    // Restored in the finally below like every other part of the contract, so
+    // a watcher's own cycle before or after keeps the level it was running at.
+    // An installed level is different and deliberately not touched here — it
+    // outlives the request, which is its whole point.
+    if (request.logReset) resetLogLevel()
+    if (request.logInstall) installLogLevel(request.logInstall)
+    if (request.log) setLogLevel(request.log)
+
     for (const key of ['json', 'tool', 'tools', 'requested']) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
@@ -437,6 +451,11 @@ async function withRequestOutput(request, run) {
         return await run()
     } finally {
         Object.assign(runtime.options, prior)
+        // Back to where the level RESTS, not to what it was a moment ago.
+        // An installed level survives the request; a per-request --log does
+        // not; and a --log-reset in this same request has already moved the
+        // resting point, so restoring "the previous level" would undo it.
+        setLogLevel(restingLogLevel())
     }
 }
 

package/src/logger.js

@@ -30,7 +30,7 @@ import Gauge from 'gauge'
 import { Writable } from 'node:stream'
 import runtime from './runtime.js'
 import { useLogger } from './engine.js'
-import { onLoad } from './lifecycle.js'
+import { onLoad, onFinalized } from './lifecycle.js'
 import { captureWarning, captureFault } from './report.js'
 
 // Custom level — `notice` slots between info and warn. Used by mikser
@@ -355,6 +355,111 @@ export function addLogTransport(entry) {
     return true
 }
 
+// The levels a person can ask for, in pino's order.
+export const LOG_LEVELS = ['trace', 'debug', 'info', 'notice', 'warn', 'error', 'fatal', 'silent']
+
+// What the run was configured with, so a reset has something to return to.
+let baseLevel = 'info'
+// { level, expiresAt } — set by --log-install, survives the request that set it.
+let installedLevel = null
+
+// Move the level, and mean it.
+//
+// `--debug` used to set runtime.engine.logger.level and stop there, which did
+// nothing observable: the pino INSTANCE accepted debug records while the
+// terminal stream still filtered them at the level it was constructed with,
+// so they were accepted and discarded. It only ever worked when a logging
+// transport happened to be configured, because that is the one path that
+// rebuilt the logger. Measured on 10.4.0: identical output with and without
+// the flag, down to the line count.
+//
+// So the stream entry moves too, and the instance is rebuilt over the live
+// stream list the way addLogTransport already does — same swap, so a transport
+// added earlier survives.
+//
+// TRANSPORTS KEEP THEIR OWN LEVEL. They were built with the level they
+// declared, and `--log debug` is a statement about what the operator wants to
+// SEE, not an instruction to flood Better Stack. A transport that wants more
+// says so in its own entry.
+export function setLogLevel(level) {
+    if (!LOG_LEVELS.includes(level)) return false
+    if (currentStreams === null || !runtime.engine) return false
+    // Index 0 is the terminal entry — see createMikserLogger, where the list
+    // is seeded with it before any transport is appended.
+    currentStreams[0] = { ...currentStreams[0], level }
+    currentLevel = level
+    runtime.engine.logger = pino(
+        { level: 'trace', customLevels: CUSTOM_LEVELS },
+        pino.multistream(currentStreams),
+    )
+    return true
+}
+
+// The level a run starts at, remembered so --log-reset has a target.
+export function rememberBaseLevel(level) {
+    if (LOG_LEVELS.includes(level)) baseLevel = level
+}
+
+// Raise the level on a RUNNING instance, until it expires.
+//
+// The case a per-request flag structurally cannot serve: a watcher's own
+// rebuilds. Today the only way to make a misbehaving production instance
+// verbose is to restart it — which drops every connected MCP and drive
+// session, and is the incident path, so the tool you need is available only by
+// performing the risky act you are trying to diagnose.
+//
+// EXPIRES, because the failure mode is a full disk weeks later with nobody
+// remembering who asked. It also dies with the process, so a restart is a
+// second guarantee rather than the only one.
+export function installLogLevel(level, ttlMs = INSTALLED_LOG_TTL_MS) {
+    if (!LOG_LEVELS.includes(level)) return false
+    installedLevel = { level, expiresAt: Date.now() + ttlMs }
+    return setLogLevel(level)
+}
+
+export function resetLogLevel() {
+    installedLevel = null
+    return setLogLevel(baseLevel)
+}
+
+// What is in force, and whether an installed level has run out. Called at the
+// top of a cycle so expiry lands on a build boundary rather than mid-render.
+export function applyInstalledLogLevel() {
+    if (!installedLevel) return null
+    if (Date.now() >= installedLevel.expiresAt) {
+        const expired = installedLevel.level
+        installedLevel = null
+        setLogLevel(baseLevel)
+        return { expired, level: baseLevel }
+    }
+    if (currentLevel !== installedLevel.level) setLogLevel(installedLevel.level)
+    return { level: installedLevel.level, expiresAt: installedLevel.expiresAt }
+}
+
+// Where the level RESTS between requests: an installed one if there is one,
+// otherwise what the run was configured with.
+//
+// The single rule the restore needs. Putting back "the level before this
+// request" instead was wrong for exactly one case and it was the important
+// one: --log-reset captured debug, cleared it, and the restore put debug back,
+// so the reset appeared to do nothing.
+export function restingLogLevel() {
+    return installedLevel?.level ?? baseLevel
+}
+
+// What is in force right now, so a caller can put it back.
+export function currentLogLevel() {
+    return currentLevel ?? baseLevel
+}
+
+export function installedLogLevel() {
+    return installedLevel ? { ...installedLevel } : null
+}
+
+// Thirty minutes: long enough to reproduce something on a live instance,
+// short enough that forgetting costs a log file rather than a disk.
+export const INSTALLED_LOG_TTL_MS = 30 * 60 * 1000
+
 // Replace the bootstrap logger (built by engine.setup() with the
 // terminal-only stream) with one that includes any third-party
 // transports from runtime.config.logging.transports. Runs at onLoad
@@ -422,3 +527,38 @@ export function updateProgressDetails(details) {
         currentBar.value / currentBar.total,
     )
 }
+
+// An installed level, disclosed and expired, once per cycle.
+//
+// Disclosed for the reason an installed command is: it is state left on a live
+// instance that changes what the process does, and the person who finds it
+// weeks later is not the person who set it. A level at debug is quieter to
+// leave behind than a probe and louder in effect — the deployment's out log is
+// already 1.6MB, and a watcher rebuilding on every editor save at debug grows
+// it fast. The failure lands as a full disk with nobody remembering who asked.
+//
+// Expiry is checked here rather than on a timer so it lands on a build
+// boundary instead of mid-render, and the level also dies with the process, so
+// a restart is a second guarantee rather than the only one.
+//
+// onFinalized, matching where the commands plugin announces an installed
+// command — the report is reset at the top of a cycle, and a warning raised
+// anywhere earlier than the last hook did not survive into the document a
+// forwarded --json emits. Measured, not assumed: on onImport and on onFinalize
+// the line reached the instance's log and the report stayed empty.
+onFinalized(() => {
+    const state = applyInstalledLogLevel()
+    if (!state) return
+    const logger = useLogger()
+    if (state.expired) {
+        logger?.info('Log level installed with --log-install has expired; back to %s', state.level)
+        return
+    }
+    const minutes = Math.max(0, Math.round((state.expiresAt - Date.now()) / 60000))
+    logger?.warn(
+        { code: 'log-level-installed', level: state.level, expiresIn: `${minutes}m` },
+        'This instance is running at log level %s, installed with --log-install — it is not the '
+        + 'configured level and it is not this build asking for it. Expires in %dm, or on --log-reset, '
+        + 'or when the process restarts.',
+        state.level, minutes)
+})

package/src/plugins/commands.js

@@ -1,8 +1,60 @@
 import { execaCommand } from 'execa'
+import { cliOption } from '../cli.js'
 import lineReader from 'line-reader'
 import { promisify } from 'util'
 import _ from 'lodash'
 
+// The hooks a command can hang off.
+//
+// ONE flag naming a hook, not fifteen flags named after hooks. The same shape
+// as `--tool <name>`: a plugin claims one word for an open-ended registry
+// rather than one word per entry. Fifteen would have reserved `--render`,
+// `--process`, `--load`, `--import`, `--persist` and `--cancel` at the top
+// level for one plugin — words core plausibly wants (a `--render <entity>` is
+// not hard to imagine) — and put fifteen near-identical rows in `--help`.
+const HOOKS = new Set([
+    'load', 'loaded', 'import', 'imported', 'process', 'processed',
+    'persist', 'persisted', 'beforeRender', 'render', 'afterRender',
+    'cancel', 'canceled', 'finalize', 'finalized',
+])
+
+// `load` is declarable in config and unreachable from the CLI: options are
+// declared DURING the load phase and the table is not parsed until after it,
+// so runtime.options is still empty when onLoad fires.
+//
+// Named and REFUSED rather than left out of the hook list. Omitting it would
+// answer `--command load=...` with "no hook named load", which is untrue —
+// there is such a hook, it is simply not one the command line can reach, and a
+// wrong reason sends someone looking for a typo. The refusal says what to do
+// instead.
+const CLI_UNREACHABLE = new Map([
+    ['load', 'the option table is parsed after the load phase, so a --command on it could never fire. '
+        + 'Declare it in the config instead: commands({ load: ... }).'],
+])
+
+// Never expected on a successful build, so their absence is not a finding.
+const CONDITIONAL = new Set(['cancel', 'canceled'])
+
+// `hook=command`, split on the FIRST `=` so a command may contain its own.
+function parseHookCommand(value) {
+    const at = value.indexOf('=')
+    if (at < 1) {
+        throw new Error(`--command expects <hook>=<command>, got ${JSON.stringify(value)}. `
+            + `Hooks: ${[...HOOKS].join(', ')}`)
+    }
+    const hook = value.slice(0, at).trim()
+    const command = value.slice(at + 1).trim()
+    if (!HOOKS.has(hook)) {
+        throw new Error(`--command: no hook named ${JSON.stringify(hook)}. `
+            + `Hooks: ${[...HOOKS].join(', ')}`)
+    }
+    if (CLI_UNREACHABLE.has(hook)) {
+        throw new Error(`--command ${hook}=: ${CLI_UNREACHABLE.get(hook)}`)
+    }
+    if (!command) throw new Error(`--command ${hook}=: no command given`)
+    return { hook, command }
+}
+
 export function commands(options = {}) {
     return ({
         runtime,
@@ -26,6 +78,117 @@ export function commands(options = {}) {
         const eachLine = promisify(lineReader.eachLine)
         const running = {}
 
+        // Declared here, in the load phase, and READ in the hook below.
+        // Reading at construction is always undefined — the option table is
+        // not parsed until after this runs.
+        //
+        // Repeatable, so several hooks can be driven in one invocation. The
+        // collector is remembered by cliOption and replayed when an instance
+        // re-parses a forwarded client's argv, so the forwarded path sees the
+        // same array the local one does.
+        const collect = (value, previous = []) => [...previous, parseHookCommand(value)]
+        cliOption('--command <hook=command>',
+            'run a command at a lifecycle hook for THIS run only, e.g. '
+            + '--command finalized="node deploy/publish.mjs". Repeatable. '
+            + `Hooks: ${[...HOOKS].join(', ')}`,
+            collect, [])
+        // Installed on the instance rather than spent on one request.
+        //
+        // --command alone cannot serve the case it was asked for. A watcher's
+        // OWN rebuilds — the ones a file save triggers, which is the whole
+        // point of watching — run nothing, so a probe fires only when a build
+        // is forwarded by hand. Installing puts it on the instance, where
+        // every cycle sees it until it is cleared.
+        cliOption('--command-install <hook=command>',
+            'install a command on the running instance, so its own rebuilds run it too. '
+            + 'Repeatable. Cleared with --command-reset.',
+            collect, [])
+        cliOption('--command-reset [hook]',
+            'clear commands installed with --command-install: all of them, or one hook\'s.')
+
+        // Said once per hook per process, not once per cycle: a watcher would
+        // otherwise repeat it on every rebuild.
+        const announced = new Set()
+
+        // Commands installed on THIS process by a forwarded --command-install.
+        //
+        // Lives in the plugin's closure rather than runtime.options because
+        // options are swapped per request and restored after — which is
+        // exactly right for --command and exactly wrong for something whose
+        // point is to outlive the request that set it.
+        const installed = new Map()
+
+        // Applied at the top of every hook: idempotent, so it does not matter
+        // which hook of the cycle sees the request first, and by the next
+        // cycle the request's options are gone while `installed` remains.
+        function applyInstallRequest() {
+            const reset = runtime.options?.commandReset
+            if (reset !== undefined && reset !== false) {
+                const cleared = reset === true
+                    ? [...installed.keys()]
+                    : installed.has(reset) ? [reset] : []
+                if (reset === true) installed.clear()
+                else installed.delete(reset)
+                if (cleared.length) {
+                    useLogger()?.info('Cleared installed command(s) at %s', cleared.join(', '))
+                }
+            }
+            const requested = runtime.options?.commandInstall
+            if (!Array.isArray(requested) || !requested.length) return
+            // An instance is what there is to install ON. A one-shot exits
+            // with the process, so installing is the same as --command and
+            // saying nothing would let someone believe it persisted.
+            if (!runtime.options?.watch && !runtime.options?.server) {
+                if (!announced.has('no-instance')) {
+                    announced.add('no-instance')
+                    useLogger()?.warn({ code: 'command-install-without-instance' },
+                        'Nothing to install on — this is a one-shot build, not a watcher, so '
+                        + '--command-install ran once and exits with the process, exactly like --command.')
+                }
+            }
+            for (const { hook, command } of requested) {
+                const list = installed.get(hook) ?? []
+                if (!list.includes(command)) installed.set(hook, [...list, command])
+            }
+        }
+
+        // NOT registered as a tool, deliberately.
+        //
+        // Listing what is attached is worth having, and `--tool commands` was
+        // the obvious shape — the registry forwards report-only runs to the
+        // instance, so it would answer from the process that holds the state.
+        // But the registry is mirrored into MCP over HTTP, its endpoint filter
+        // defaults to allow-all, and a command string routinely carries a
+        // path, a host or a token. That turns "list the hooks" into handing an
+        // authenticated web client a map of the build box.
+        //
+        // There is no per-tool scope to lean on: routes declare reachability
+        // (public / token / loopback), tools declare only `mutates`. A
+        // `scope: 'admin'` key here would be decorative — nothing enforces it
+        // — and a decorative guard is worse than none, because it reads like
+        // one.
+        //
+        // Installing is not the exposure: it needs the unix socket, which is
+        // chmod 0600, so anyone who can reach it already runs as this user and
+        // could run the command directly. Reading over HTTP is a different
+        // boundary, which is why this half is the half that had to go.
+        //
+        // What answers the question meanwhile: every installed command is
+        // announced on every cycle under `command-from-cli`, so the last
+        // build's log or its --json report names each one. A standalone
+        // listing wants per-tool scoping in the registry first.
+
+        // Which requested hooks actually fired this cycle.
+        //
+        // `loaded` is the case that matters: it fires for a local build and
+        // NOT for one forwarded to a running instance, because that instance
+        // loaded at startup and a rebuild does not repeat the load phase. So
+        // the same command does different things depending on whether a
+        // watcher happens to be up, and until now it did so in silence.
+        // Checked generically rather than special-casing that one hook, since
+        // the interesting cases are the ones nobody predicted.
+        const fired = new Set()
+
         async function executeCommand(command) {
             const logger = useLogger()
             if (_.endsWith(command, '&')) {
@@ -51,9 +214,74 @@ export function commands(options = {}) {
             if (typeof cmds == 'function') cmds = await cmds()
             if (typeof cmds == 'string') cmds = [cmds]
 
+            // From argv, read HERE rather than merged into `options` at
+            // construction — that is the whole rule for plugin CLI options,
+            // and it is also what makes a forwarded request overwrite instead
+            // of accumulate. The instance applies a client's flags onto
+            // runtime.options for one cycle and restores them after, so this
+            // reads whatever THIS request asked for. Registering a hook per
+            // request would have made two clients' commands add up; there is
+            // one hook, registered once, reading a value that changes.
+            applyInstallRequest()
+
+            const requested = runtime.options?.command
+            const perRequest = (Array.isArray(requested) ? requested : [])
+                .filter(entry => entry?.hook === hook)
+                .map(entry => entry.command)
+            // Installed ones outlive the request that set them, so they run
+            // for the instance's OWN rebuilds too — which is the case
+            // --command alone cannot serve.
+            const fromInstalled = installed.get(hook) ?? []
+            const fromCli = [...perRequest, ...fromInstalled]
+            for (const command of fromCli) {
+                // Under a code, in the report, with the command.
+                //
+                // A build is otherwise a function of the repository — same
+                // commit, same bytes, and --fingerprint can prove it. A
+                // command from argv makes it a function of the repo AND how it
+                // was invoked, so an agent, a person and CI can run "the same
+                // build" and get different output. Warn rather than log:
+                // warnings are a view of logger.warn in the report, so a
+                // fingerprint taken from this build stays interpretable
+                // instead of quietly meaning something else.
+                // A per-request command is announced once per process: it is
+                // in the invocation you just typed. An INSTALLED one is
+                // announced every cycle, because you may have set it an hour
+                // ago and each build's report has to carry the fact that this
+                // build was not a function of the repository alone.
+                const key = `${hook}:${command}`
+                if (fromInstalled.includes(command) || !announced.has(key)) {
+                    announced.add(key)
+                    useLogger()?.warn({ code: 'command-from-cli', hook, command },
+                        'Running a command from the command line at the %s hook: %s. This build is a '
+                        + 'function of how it was invoked as well as of the repository — the same commit '
+                        + 'built without this flag can differ. Commands that write into the output folder '
+                        + 'also fail --audit-output, which hashes each file as it is written.',
+                        hook, command)
+                }
+            }
+            cmds = [...cmds, ...fromCli]
+
             for (let command of cmds) {
                 await executeCommand(command)
             }
+            if (fromCli.length) fired.add(hook)
+        }
+
+        // Anything asked for that never ran, said at the end of the cycle.
+        function reportUnfired() {
+            const requested = runtime.options?.command
+            if (!Array.isArray(requested)) return
+            const missed = [...new Set(requested.map(entry => entry?.hook))]
+                .filter(hook => hook && !fired.has(hook) && !CONDITIONAL.has(hook))
+            fired.clear()
+            if (!missed.length) return
+            useLogger()?.warn({ code: 'command-hook-not-reached', hooks: missed },
+                'Asked to run a command at %s, and that hook did not fire this cycle. A build forwarded '
+                + 'to a running instance reuses one that loaded at startup, so load-phase hooks belong '
+                + 'to the instance rather than to the request. Stop the instance to run the command, or '
+                + 'move it to a per-cycle hook.',
+                missed.join(', '))
         }
 
         onLoad(async () => await executeCommands('load'))
@@ -70,7 +298,11 @@ export function commands(options = {}) {
         onCancel(async () => await executeCommands('cancel'))
         onCancelled(async () => await executeCommands('canceled'))
         onFinalize(async () => await executeCommands('finalize'))
-        onFinalized(async () => await executeCommands('finalized'))
+        onFinalized(async () => {
+            await executeCommands('finalized')
+            // Last, so every other hook has had its chance.
+            reportUnfired()
+        })
 
         return { executeCommand }
     }

package/src/report.js

@@ -10,6 +10,7 @@
 // reworded — which is exactly the kind of assertion that should not break
 // when someone improves the wording.
 import runtime from './runtime.js'
+import { installedLogLevel } from './logger.js'
 import { isReportOnlyRun } from './tools.js'
 
 // A transport that can serve the build report declares itself here, at
@@ -529,6 +530,27 @@ export function buildReport() {
         cycleId: cycle?.id ?? null,
         startedAt: cycle?.startedAt ?? null,
         finishedAt: cycle?.finishedAt ?? null,
+        // A log level installed on this instance with --log-install.
+        //
+        // Read HERE, at emit time, rather than raised as a warning during the
+        // cycle. A warning was the obvious shape — it is how an installed
+        // command is disclosed — and it does not survive into the document a
+        // forwarded --json emits: the line reached the instance's log from
+        // onImport, onFinalize and onFinalized alike, and `warnings` stayed
+        // empty every time. Reading state at emit has no ordering to get
+        // wrong, and this is a FACT ABOUT THE INSTANCE rather than an event in
+        // the cycle, so it reads better as a field than as an entry anyway.
+        //
+        // Null is the normal case, and its absence is what tells a reader the
+        // level is the configured one.
+        logLevel: installedLogLevel()
+            ? {
+                level: installedLogLevel().level,
+                installed: true,
+                expiresInMinutes: Math.max(0,
+                    Math.round((installedLogLevel().expiresAt - Date.now()) / 60000)),
+            }
+            : null,
         // What the run COST, per phase, in milliseconds.
         //
         // `finishedAt - startedAt` is not this. It spans the processing cycle