mikser-io 10.4.0 → 10.6.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. |

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.4.0",
+  "version": "10.6.0",
   "files": [
     "app.js",
     "index.js",

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, rememberBaseLevel, applyLogRequest,
+    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
+        // The same call the instance makes for a forwarded request — see
+        // applyLogRequest. Two implementations drifted within one commit.
+        const logRefusal = applyLogRequest({
+            log: asked,
+            logInstall: runtime.options.logInstall,
+            logReset: runtime.options.logReset,
+        })
+        if (logRefusal) throw new Error(logRefusal)
+        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, restingLogLevel, applyLogRequest, LOG_LEVELS,
+} from './logger.js'
 import { emitReport } from './report.js'
 import { pluginOptionsFrom } from './cli.js'
 
@@ -237,6 +240,17 @@ function captureOutput(onChunk) {
 // 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.
+// Does this request name a level that does not exist? Pure, so the refusal
+// can be decided before anything is applied.
+function logRequestRefusal(request) {
+    for (const [flag, level] of [['--log', request?.log], ['--log-install', request?.logInstall]]) {
+        if (level !== undefined && level !== null && !LOG_LEVELS.includes(level)) {
+            return `${flag} ${level}: no such level. Levels: ${LOG_LEVELS.join(', ')}`
+        }
+    }
+    return null
+}
+
 function configMismatch(theirs) {
     if (!theirs) return null
     const mine = path.resolve(runtime.options.config ?? 'mikser.config.js')
@@ -366,6 +380,26 @@ function refuseClear(socket, request) {
     return true
 }
 
+// A level the instance cannot use.
+//
+// Validated where the request ARRIVES rather than where it is applied, because
+// applying it is exactly what a bad level cannot do: setLogLevel returns false
+// and, before this, nobody read it — so `--log chatty` exited 1 locally and
+// built normally with a watcher up. The refusal frame is how the instance says
+// no to everything else, and a client that mistypes a level deserves the same
+// answer whether or not something happens to be listening.
+function refuseLogLevel(socket, request) {
+    const refusal = logRequestRefusal(request)
+    if (!refusal) return false
+    frame(socket, {
+        type: 'refused',
+        reason: refusal,
+        detail: 'The instance would otherwise have built normally and said nothing, which is the '
+            + 'forwarded-versus-local split this surface exists to remove.',
+    })
+    return true
+}
+
 // Which process to restart.
 //
 // "Restart it" is only actionable if you know which `it` — and the machine
@@ -418,11 +452,32 @@ 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 }
-    for (const key of ['json', 'tool', 'tools', 'requested']) {
+
+    // 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.
+    // Captured BEFORE applyLogRequest, which writes `info`.
+    //
+    // `info` is here because --log silent turns the progress bar off through
+    // it, and without a restore one silent request left the instance with no
+    // bar for the rest of its life. Capturing after the call would have
+    // recorded the value the call just wrote and restored nothing — the same
+    // shape of mistake, one line further on.
+    for (const key of ['json', 'tool', 'tools', 'requested', 'info']) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
     }
 
+    // The same call the argv path makes — see applyLogRequest. The level was
+    // validated at arrival by refuseLogLevel, so a refusal here is impossible;
+    // it is asserted rather than ignored, because "cannot happen" is how the
+    // first version of this silently accepted a bad level.
+    const refusal = applyLogRequest(request)
+    if (refusal) throw new Error(refusal)
+
     // Whatever the client's argv said about a PLUGIN's options.
     //
     // The instance parsed its own argv and never saw the client's, so a flag a
@@ -437,6 +492,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())
     }
 }
 
@@ -539,6 +599,7 @@ export function serveInstance() {
                     // writes anything.
                     if (refuseUnknownFlags(socket, request)) return
                     if (refuseClear(socket, request)) return
+                    if (refuseLogLevel(socket, request)) return
                     const wrongConfig = configMismatch(request.config)
                     if (wrongConfig) return refuseConfig(socket, request, wrongConfig)
                     const movedFile = await configStale()

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
@@ -386,16 +491,49 @@ export function trackProgress(name, total) {
     if (!name || !total) return
     const logger = useLogger()
     logger.debug('%s started: %d', name, total)
-    if (!process.stdout.isTTY || !runtime.options.info) return
-    currentBar = { name, total, value: 0, started: Date.now() }
-    ensureGauge().show({ section: name, subsection: `0/${total}` }, 0)
+    // The bar writes to stdout, and stdout is where --json and --tool put
+    // their DOCUMENT. Forwarded, those writes are captured and framed to the
+    // client, so the gauge landed inside the JSON:
+    // `^[[?25lDocuments import: >416/800` at byte 0, and JSON.parse threw —
+    // 4 runs in 10 at the default level on an 800-document corpus.
+    //
+    // Checked HERE rather than through runtime.options.info, because this is
+    // the actual invariant and info is a preference. A preference can be
+    // forgotten on a path; an invariant stated at the one place a bar starts
+    // cannot.
+    const carriesDocument = runtime.options?.json || runtime.options?.tool || runtime.options?.tools
+
+    // TRACKED always, DRAWN only where a bar belongs.
+    //
+    // The two used to be one decision, so anything that could not draw also
+    // stopped counting — and `stopProgress` returns early without a bar, which
+    // is where the "finished: N in Ns" line comes from. A piped build
+    // therefore reported no phase timings at all, and suppressing the bar for
+    // --json would have extended that to every machine reading the output.
+    // Losing the graphics is the point; losing the information is not.
+    const drawn = !carriesDocument && Boolean(process.stdout.isTTY) && Boolean(runtime.options.info)
+    currentBar = { name, total, value: 0, started: Date.now(), drawn, milestone: 0 }
+    if (drawn) ensureGauge().show({ section: name, subsection: `0/${total}` }, 0)
+    else logger.info({ code: 'progress', phase: name, total, value: 0 }, '%s: 0/%d', name, total)
 }
 
 export function updateProgress() {
     if (!currentBar) return
     currentBar.value++
-    const { name, total, value } = currentBar
-    gauge?.show({ section: name, subsection: `${value}/${total}` }, value / total)
+    const { name, total, value, drawn } = currentBar
+    if (drawn) {
+        gauge?.show({ section: name, subsection: `${value}/${total}` }, value / total)
+    } else {
+        // Quartiles, not every item: a bar redraws in place and costs one
+        // line, a log record does not. 800 documents is 800 lines of noise if
+        // this counts the way the bar does.
+        const reached = Math.floor((value / total) * 4)
+        if (reached > currentBar.milestone && value < total) {
+            currentBar.milestone = reached
+            useLogger()?.info({ code: 'progress', phase: name, total, value },
+                '%s: %d/%d', name, value, total)
+        }
+    }
     if (value >= total) stopProgress()
 }
 
@@ -404,11 +542,15 @@ export function stopProgress() {
     const logger = useLogger()
     const { name, total, value, started } = currentBar
     gauge?.hide()
+    // Structured either way, so a machine reading --json's stderr gets the
+    // same facts a person reads off the bar.
     if (value < total) {
-        logger.warn('%s unfinished: %d', name, total - value)
+        logger.warn({ code: 'progress-unfinished', phase: name, total, value, missing: total - value },
+            '%s unfinished: %d', name, total - value)
     } else {
-        const elapsed = Math.round((Date.now() - started) / 1000)
-        logger.info('%s finished: %d %ds', name, total, elapsed)
+        const ms = Date.now() - started
+        logger.info({ code: 'progress-finished', phase: name, total, ms },
+            '%s finished: %d %ds', name, total, Math.round(ms / 1000))
     }
     currentBar = null
 }
@@ -422,3 +564,70 @@ export function updateProgressDetails(details) {
         currentBar.value / currentBar.total,
     )
 }
+
+// What a caller asked for about logging, applied the same way from argv and
+// from a forwarded request.
+//
+// It was written twice and the copies drifted immediately: the argv path threw
+// on an unknown level and set `info`, the forwarded path called setLogLevel and
+// ignored the false it returns. So `--log chatty` exited 1 locally and built
+// normally with a watcher up, and `--log silent` left the progress bar running
+// on an instance. The same forwarded/local split --json and --force each had,
+// and this feature's own argument against itself: a flag that lies is worse
+// than a flag that is missing.
+//
+// Returns an error STRING rather than throwing, because the two callers need
+// different things from a failure — argv throws, the instance refuses over the
+// socket — and a shared implementation should not decide that for them.
+export function applyLogRequest({ log, logInstall, logReset } = {}) {
+    for (const [flag, level] of [['--log', log], ['--log-install', logInstall]]) {
+        if (level !== undefined && level !== null && !LOG_LEVELS.includes(level)) {
+            return `${flag} ${level}: no such level. Levels: ${LOG_LEVELS.join(', ')}`
+        }
+    }
+    if (logReset) resetLogLevel()
+    if (logInstall) installLogLevel(logInstall)
+    if (log) setLogLevel(log)
+
+    // A bar on top of debug output is noise, and silent means silent.
+    const level = log || logInstall
+    if (level === 'trace' || level === 'debug' || level === 'silent') {
+        runtime.options.info = false
+    }
+    return null
+}
+
+// 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/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