arkgate 4.8.23 → 4.8.24

package/CHANGELOG.md

@@ -96,6 +96,74 @@ in the immutable pre-2.0 archive linked below.
   Existing configs keep whatever URL they already have. Editor completion
   matches the 4.x line you just installed.
 
+## 4.8.24 — 2026-09-29
+
+**Patch** over **4.8.23**. Follow-ups to the hierarchical slices shipped in 4.8.23
+(issues #335–#338), every defect a full audit of the gate and its add-ons
+confirmed, and much lower memory per validation (#339). **Write. Check. Ship.**
+**No required config migration:** a config that loads in 4.8.23 still loads;
+ids that changed meaning warn (`CONFIG_CHILD_SLICES_INERT`,
+`CONFIG_SLICE_LEGACY_STARS_ID`) and keep their 4.8.23 verdict for one release.
+No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Minimum version 4.8.24 for the new config fields** (`sharedImportsSlice`
+object form with `stopAt`, `childSlices.message`, `childSlices.siblings.ratchet`).
+arkgate 4.8.23 and older reject them at config load. Pin 4.8.24 in the write
+hook and CI first.
+
+**Status: released** (tag `v4.8.24`). This file does not assert registry
+state; run `npm view arkgate@4.8.24 version` to confirm (#314).
+
+### Added
+- `sharedImportsSlice` accepts `{ "mode": "deny-cross-parent", "stopAt": [...] }`. The whole-graph `CROSS_PARENT_VIA_SHARED` walk never starts at or passes through a stop file, so a declared composition root (`kernel/bootstrap.ts`, `kernel/registrations/**`) is no longer reported as a crossing. `stopAt` matches like a shared root or an alias glob; a stop that covers the whole tree or a whole layer root is rejected. Findings carry `via`, and doctor `sharedWalkHubs` names a likely undeclared composition root. Adding stops is a weakening policy delta. The string forms are unchanged. arkgate 4.8.23 and older reject the object (issue [#335](https://github.com/pedroknigge/arkgate/issues/335)).
+- Optional `childSlices.message` sets the text for inner-wall findings (`CROSS_SIBLING_SLICE`, universe common code importing a child). Without it ArkGate uses its own text; the rule `message` stays the universe-wall text and is never reused on inner-wall findings. Same text in ark-check, CI, the write hook, MCP, and ESLint (issue [#337](https://github.com/pedroknigge/arkgate/issues/337)).
+- Optional `childSlices.siblings.ratchet`: `true` always fails a new advisory crossing, `false` only measures (issue [#336](https://github.com/pedroknigge/arkgate/issues/336)).
+- `arkgate mcp` / `ark mcp` start the stdio MCP server (same as `arkgate-mcp`).
+- ESLint: warn-level `ark/architecture-advisory` rule (findings ark-check reports as warnings) and `ark/arkrules-structure` (ArkRules structure sensors on the same Effective Contract).
+- New advisory `ARKRULE_FILE_UNREFERENCED` for an `arkrules/*.json` the config does not reference, and `doctor.rulesMigration`.
+- `ark-dashboard --help`, `--version`, `--once`, `ARK_DASHBOARD_URL`.
+- `npm run bench:memory` regression guard (budgets in `eval/performance/memory-budgets.v1.json`).
+
+### Changed
+- **Memory and speed.** ark-check, `--doctor`, the write hook, ApplyPatch preflight, the MCP server and the ESLint plugin use much less memory; verdicts are byte-identical. On a 20k-file repo: ark-check peak 422 → 303 MB (3.7 → 2.3 s), ApplyPatch hook 649 → 414 MB (9.5 → 3.6 s), Write hook 163 → 146 MB (0.68 → 0.24 s), MCP server after 50 calls 725 → 442 MB. Sources are read one at a time and released, the facts hash streams, module resolution is memoized per run, the Write/Edit hook no longer walks the whole `include` tree for tsconfig aliases, and preflight reuses base parses.
+- Advisory sibling crossings are advisory on day 1. The anti-growth ratchet is judged per rule and turns on only when the baseline in use already records an advisory sibling crossing of that rule (issue [#336](https://github.com/pedroknigge/arkgate/issues/336)).
+- `CONFIG_CHILD_SLICES_VERSION` (and the other new-key version warnings) fire only with evidence that the repo pins an older arkgate (exact `package.json` dependency, installed copy, lockfile, hook script, or CI workflow). The finding points at that file and line and names the version to bump to (issue [#338](https://github.com/pedroknigge/arkgate/issues/338)).
+- `childSlices` on a rule without `peerIsolation: true` and `allowed: false` still loads (as in 4.8.23) but is inert; ark-check now warns `CONFIG_CHILD_SLICES_INERT` and says how to fix it (add both flags to the rule, or remove `childSlices`). No config that loads in 4.8.23 fails to load.
+- `sliceIdentity: "stars"` keeps every star binding (`modules/*/api/*` binds `orders/api/v1`, not `api/v1`). **Migration:** a `sliceAliases` `to` or an `allowedCrossSlice` / `childSlices.allowedCrossSlice` entry written against the 4.8.23 id (`api/v1/x`, `api/v1`) keeps loading and keeps its 4.8.23 verdict for this release: the alias joins the universe whose old id it names, and the allowance still clears the edge it cleared. ark-check warns `CONFIG_SLICE_LEGACY_STARS_ID` and names the new id to write (`orders/api/v1/x`). A legacy alias target is rejected at config load only when it maps to more than one universe shape of the rule. The legacy form is removed in the next minor release.
+- `childSlices.commonFolders` counts only a folder directly under the universe; the same name inside a child belongs to that child.
+- The write hook fails closed: if it cannot run inside an Ark project (invalid config, missing ArkRules file, missing `dist/`), governed writes are denied with exit 2 (`WRITE_GATE_UNAVAILABLE`) instead of exit 1, which hosts let through. The hook finds its project root like ark-check: a set `--root-env` variable, else the root that holds `ark.config.json`, else it walks up from the payload (written file, `cwd`, `workspace_roots`) to the nearest `ark.config.json`. A write outside any Ark project (no `ark.config.json` found) is allowed, as in 4.8.23.
+- `ark start --apply --remove-host <host>` removes only the Ark hook entries from a merged `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json` or `.agents/hooks.json` (same identity as the merge) and keeps every user key and hook; the file is deleted only when nothing else remains. "customized" is reported only when the Ark entry itself was edited.
+- An enforced invariant with `coverage: { test: false }` and no `coverage.symbol` is uncovered; `coverage.symbol: "Class.member"` needs the member declared in that class.
+- ArkOrder `apply()` only accepts a proposal bound to the current Release (`ARKORDER_STALE_PROPOSAL`); `restore()` never changes ξ or rolls the version back; `ReleaseStore.load()` is validated; the plane advances only after `save()`; `informationBudget` is enforced when a Release is created.
+- ArkRun: the default event buffer is capped and settles after local delivery; broker handoff failures are recorded (`event.handoffFailed`); config kernels with canonical layer names enforce hard observed-layer-flow.
+- `ark-check --update-baseline` always freezes the whole tree and refuses `--changed` / `--local`.
+
+### Fixed
+- `--changed`, `--local`, `--against` and `--persona` no longer give a false green: paths resolve relative to `--root` (monorepo packages), non-ASCII names are kept, large or failed git listings exit 2, and a missing base ref exits 2 (`changed-needs-base`) instead of "nothing changed".
+- `--changed` catches a new `CROSS_PARENT_VIA_SHARED` created by editing only a shared-root file, and no longer warns `CONFIG_LAYER_PATTERN_NO_MATCHES` for untouched layers.
+- `ark-check --report`, `latest.json`, `--doctor` and `ark status` agree on frozen versus active findings.
+- Write path parity with CI: the hook, `validate_code`, `ark_prepare_write`, `ark_prepare_change` and ApplyPatch preflight enforce ArkRules structure sensors and ArkOrder editor sensors, load ArkRules like ark-check, handle realpath aliases, and accept the full Codex `apply_patch` format.
+- MCP: `validate_code` / `ark_check` output schemas pass MCP SDK validation (tools no longer disappear); a stale contract returns `CONTRACT_STALE`; `ark_status` honors `--config`; `arkgate-mcp --help` / `--version` exit.
+- MCP Registry: `server.json` runs `npx arkgate@<version> mcp --root .`; the old descriptor never started the server.
+- CommonJS TypeScript consumers: `.d.cts` declarations ship and are mapped for every entry.
+- ESLint: warnings in ark-check are warnings in ESLint; messages carry the rule message and slice reason; ArkOrder rules show real text at 1-based columns; tsconfig JSONC / nearest tsconfig / `extends` are read correctly; an invalid config reports one diagnostic instead of crashing; `require('arkgate/eslint')` returns the plugin (it also carries a non-enumerable `__esModule`, so Babel `_interopRequireWildcard` and TypeScript `__importStar` still see every named export); `--cache` invalidates on contract change; forbidden-globals catches destructuring and bracket access.
+- Slices: adapter diagnostics carry `reasonId` and the universe pair; `CROSS_PARENT_VIA_SHARED` honors the universe `allowedCrossSlice`; fail-closed reasons are named in the hook and MCP; folder-form `sliceAliases` cover their subtree; the flat-parent move card counts every resolved importer; `SHARED_IMPORTS_SLICE` is catalogued.
+- Setup: `ark start --archetype/--preset` writes that shape; re-running `ark start --apply` works; `--remove-host` does not touch packages; existing `.claude/settings.json` / `.codex/hooks.json` are merged instead of skipped or wiped; `typecheck` is added only when TypeScript is present; the steward lock holds under `--strict-merge --contract-session`; `ark status --config` / `ark agents-md --config` work; starter ArkRules ids are unique.
+- ArkRules: policy delta reads base ArkRules from the base ref (demoting an enforced rule is weakening); class-shape sensors see generic classes, ignore braces in strings and regexes, and skip a `static { … }` initialization block (it is not a public member); `ArkRulesValidationError` is exported from the root.
+- ArkRun: undeclared emit/handle/depend count only kernel-traced receivers (`res.send`, `require.resolve`, rxjs `subscribe` are ignored); typed `send(Creator)` resolves names; `ArkModule.forRoot()` is a composition root; `arkgate/runtime` and `arkgate/nestjs` share one kernel chunk (`instanceof` works). A namespace import of a composition root (`import * as main from '../main'; main.ark.publisher(..)`) is traced as a kernel receiver, and an untraced receiver counts when its name carries one of the project's effective intent prefixes (configured `layers[].intentPrefixes` plus the canonical ones), not only `Domain.`/`Application.`….
+- ArkOrder: `ARKORDER_XI_FIELD_WRITE` recognizes Prisma/ORM clients by construction, `GENERIC_UPDATE` / `INGEST_WRITES_XI` false positives removed, `xi-ttl` and `information-budget` sensors emit, NaN/Infinity rejected, documented types exported, and the shipped `bin/lib/ark-order-invariants.mjs` loads.
+- Docs: the composite Action pin tracks the current release, and configuration.md names the real policy-delta entry points.
+- Generated CI workflows, host hooks and MCP entries in a project that does not
+  have arkgate as a local dependency run `npx -y -p arkgate@<exact version> <bin>`
+  instead of a bare `npx ark-check` / `npx arkgate-mcp` (npm resolved those as a
+  nonexistent package, or ran a stale global). Without a `package.json` the workflow
+  skips the install step and the npm cache. `--migrate-commands` rewrites bare runners
+  into the pinned form, and `--doctor` leads with `PACKAGE_PIN_ABSENT` when a generated
+  file still uses the local runner without the pin.
+- `ark-check --json` answers every fatal error with a JSON envelope (`POLICY_BASE_UNREADABLE` when a CI base ref such as `GITHUB_BASE_REF` cannot be read in the checkout, otherwise `CHECK_ERROR`), not only `CONFIG_INVALID`; exit code stays 2.
+- Security: CodeQL `js/polynomial-redos` in the steward email check and two incomplete-sanitization alerts are closed.
+
 ## 4.8.23 — 2026-09-28
 
 **Patch** over **4.8.22**. Hierarchical slices: the issue #326 series

package/README.md

@@ -25,11 +25,11 @@ Design the boundary before you implement. Put a small interface in front of the
 
 ## Try it
 
-One command. Preview only — no files change. Current release is **4.8.23**
+One command. Preview only — no files change. Current release is **4.8.24**
 (check npm `latest` with `npm view arkgate version`):
 
 ```bash
-npx arkgate@4.8.23 start
+npx arkgate@4.8.24 start
 ```
 
 ## What a red result looks like
@@ -320,9 +320,11 @@ queue monitors:
 
 Poll those facts from the dual bins **`ark-dashboard`** / **`arkgate-dashboard`**
 (`bin/ark-dashboard.mjs`). ANSI + polling only (no React/Ink/Blessed). Point
-`--url` / `-u` at the inspector snapshot (default
-`http://127.0.0.1:3000/snapshot`); the dashboard also fetches sibling `/outbox`
-and `/workflows`. `--interval` / `-i` is clamped to 200–60000 ms (default 2000).
+`--url` / `-u` at the inspector (`handle.url` or `handle.snapshotUrl`); the dashboard
+also fetches sibling `/outbox` and `/workflows`. `startInspector()` binds a random port
+unless you pass `{ port }`, so the fallback `http://127.0.0.1:3000/snapshot` (or
+`ARK_DASHBOARD_URL`) only matches `startInspector({ port: 3000 })`. `--interval` / `-i`
+is clamped to 200–60000 ms (default 2000); `--once`, `--help`, `--version` are supported.
 Also available as `ark dashboard` / `arkgate dashboard` (passthrough to the same bin). Kernel stays
 JSON-only; presentation stays in `bin/`.
 

package/bin/ark-check-runtime.mjs

@@ -106,7 +106,7 @@ import {
   normalize,
   walk,
 } from './lib/scan-files.mjs';
-import { configWarning } from './lib/config-warnings.mjs';
+import { configInvalidJsonEnvelope, configWarning } from './lib/config-warnings.mjs';
 import { runArchitectureScan } from './lib/architecture-scan.mjs';
 import {
   ANALYSIS_COMPLETENESS,
@@ -124,6 +124,7 @@ import {
   applyAgainstRatchet,
   bindTeamBaseRefs,
   contractSessionFrom,
+  pruneScopedPatternWarnings,
   runTeamPreflight,
   ungovernedDumpMessage,
 } from './lib/team-parliament-io.mjs';
@@ -135,7 +136,9 @@ import {
   resolveEffectiveProjectRoot,
 } from './lib/project-root.mjs';
 import { demoteArkRuleTeethUnderClassificationFloor } from './lib/rules-under-contract.mjs';
-import { localCheckEnvelope, parseArgs, resolveDesignDeltaBaseRef } from './lib/check-args.mjs';
+import {
+  effectiveBaselineName, localCheckEnvelope, parseArgs, resolveDesignDeltaBaseRef, UPDATE_BASELINE_SCOPE_MESSAGE,
+} from './lib/check-args.mjs';
 import { detectConfig, proposeForUncovered } from './lib/check-config-detect.mjs';
 import { runWatchMode } from './lib/check-watch.mjs';
 
@@ -1333,6 +1336,7 @@ async function main() {
     strictMerge: args.strictMerge || args.contractDiff,
     basePath: args.policyBase,
     baseRef: args.policyBaseRef,
+    adoptMissingBase: args.policyBaseFromTeam === true,
     acknowledgementPath: args.policyAck,
   });
   const preflight = runTeamPreflight({
@@ -1447,6 +1451,7 @@ async function main() {
     args,
   });
 
+  if (args.changed) pruneScopedPatternWarnings(warnings, root, loadGovernedFiles);
   // Align merge with extraMergeTeeth stamp: demote enforced ArkRules under classification floor.
   const preCov = computeCoverage(root, config, files, rules);
   const populatedLayerCount = Array.isArray(preCov.layers)
@@ -1515,6 +1520,8 @@ async function main() {
   }
 
   if (args.updateBaseline) {
+    // A persona can turn on --changed after parseArgs; a subset scan must never rewrite the baseline.
+    if (args.changed) { console.error(UPDATE_BASELINE_SCOPE_MESSAGE); process.exitCode = 2; return; }
     if (!contractSessionFrom(args)) {
       console.error('Growing the baseline requires --contract-session. Freeze in a law-only PR.');
       process.exitCode = 1;
@@ -1587,14 +1594,16 @@ async function main() {
       changed: args.changed,
       changedPaths,
       occurrenceKeys: baselineOccurrenceKeys(violations),
+      rules,
+      layers: config.layers,
     });
     activeViolations = ratcheted.activeViolations;
     suppressed = ratcheted.suppressed;
-  } else if (args.baseline) {
-    const baseline = readBaseline(root, args.baseline);
+  } else if (effectiveBaselineName(args, root)) {
+    const baseline = readBaseline(root, effectiveBaselineName(args, root));
     if (baseline.exists) {
       const occurrenceKeys = baselineOccurrenceKeys(violations);
-      const judged = applyAdvisorySiblingRatchet(violations, occurrenceKeys, baseline.keys);
+      const judged = applyAdvisorySiblingRatchet(violations, occurrenceKeys, baseline.keys, { rules, layers: config.layers });
       suppressed = judged.filter((_, index) => baseline.keys.has(occurrenceKeys[index]));
       activeViolations = judged.filter((_, index) => !baseline.keys.has(occurrenceKeys[index]));
       const currentKeys = new Set(occurrenceKeys);
@@ -1639,81 +1648,16 @@ async function main() {
   }
 
   if (args.rulesInventory) {
-    const { buildRulesInventory, inventoryToExtractionCard } = await import('./lib/rules-inventory.mjs');
-    const fileContents = {};
-    const fileLayers = {};
-    for (const file of files.slice(0, 400)) {
-      const rel = normalize(path.relative(root, file));
-      try {
-        fileContents[rel] = fs.readFileSync(file, 'utf8');
-        const layer = layerForFile(root, file, config.layers);
-        if (layer) fileLayers[rel] = layer;
-      } catch {
-        /* skip unreadable */
-      }
-    }
-    const contracted = [];
-    if (config.arkRules) {
-      try {
-        const { loadEffectiveArkRulesFromDisk } = await import('./lib/effective-contract-load.mjs');
-        const loaded = loadEffectiveArkRulesFromDisk(root, config);
-        for (const rule of loaded.arkRules.structure ?? []) contracted.push(rule.id);
-        for (const inv of loaded.arkRules.invariants ?? []) contracted.push(inv.id);
-      } catch {
-        /* advisory inventory still useful */
-      }
-    }
-    const inventory = buildRulesInventory({
-      fileContents,
-      fileLayers,
-      layerContexts: (config.layers ?? []).map((layer) => ({
-        name: layer.name,
-        intentPrefixes: layer.intentPrefixes ?? [],
-      })),
-      contractedRuleIds: contracted,
-    });
-    const nextPilot =
-      inventory.candidates[0] != null
-        ? inventoryToExtractionCard(inventory.candidates[0])
-        : null;
-    let evidenceLines = [];
-    let coverageEvidence = null;
-    if (config.arkRules && Object.keys(config.arkRules).length > 0) {
-      try {
-        const { summarizeRulesUnderContract, formatArkRulesEvidenceLines } = await import(
-          './lib/rules-under-contract.mjs'
-        );
-        const section = summarizeRulesUnderContract(root, config, {
-          files: files.map((file) => ({ path: normalize(path.relative(root, file)) })),
-        });
-        evidenceLines = formatArkRulesEvidenceLines(section);
-        if (section.active === true) {
-          coverageEvidence = {
-            symbolEvidence: section.symbolEvidence ?? [],
-            discarded: section.coverageStats?.discarded ?? null,
-          };
-        }
-      } catch {
-        /* inventory still useful when coverage cannot be read */
-      }
-    }
-    const payload = {
-      rulesInventory: inventory,
-      rulesMigration: {
-        inventoried: inventory.inventoried,
-        underContract: inventory.underContract,
-        frozen: inventory.frozen,
-        notAScore: true,
-      },
-      nextPilot: nextPilot,
-      ...(coverageEvidence ? { coverageEvidence } : {}),
-    };
+    // Same helper as MCP ark_rules_inventory and doctor.rulesMigration (AR15).
+    const { buildRulesInventoryPayload, formatRulesMigrationCounts } = await import(
+      './lib/rules-under-contract.mjs'
+    );
+    const { payload, evidenceLines } = buildRulesInventoryPayload(root, config, files);
+    const { rulesInventory: inventory, nextPilot } = payload;
     if (args.json) {
       console.log(JSON.stringify(payload, null, 2));
     } else {
-      console.log(
-        `Rules inventory: ${inventory.inventoried} inventoried, ${inventory.underContract} under contract, ${inventory.frozen} frozen (not a score).`
-      );
+      console.log(`Rules inventory: ${formatRulesMigrationCounts(payload.rulesMigration)}.`);
       for (const c of inventory.candidates.slice(0, 12)) {
         console.log(`  - [${c.confidence}] ${c.kind} @ ${c.file}:${c.line} — ${c.message}`);
       }
@@ -1865,6 +1809,7 @@ async function main() {
       ? renderBeginnerHtmlReport(reportPayload)
       : renderHtmlReport(reportPayload);
     const reportPath = path.isAbsolute(args.report) ? args.report : path.join(root, args.report);
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
     fs.writeFileSync(reportPath, html);
 
     const archive = archiveReportSnapshots(root, {
@@ -2087,6 +2032,8 @@ async function main() {
 }
 
 main().catch((error) => {
+  const envelope = configInvalidJsonEnvelope(error, process.argv);
+  if (envelope) console.log(envelope);
   console.error(
     process.env.ARK_DEBUG_STACK === '1' && error instanceof Error
       ? error.stack

package/bin/ark-dashboard.mjs

@@ -1,43 +1,55 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
+import {
+  DASHBOARD_DEFAULT_INTERVAL_MS,
+  DASHBOARD_DEFAULT_TIMEOUT_MS,
+  DASHBOARD_DEFAULT_URL,
+  DASHBOARD_EPHEMERAL_PORT_HINT,
+  DASHBOARD_HELP,
+  clampDashboardMs,
+  dashboardSiblingUrl,
+} from './lib/dashboard-cli.mjs';
 
-const DEFAULT_INTERVAL_MS = '2000';
-const DEFAULT_SNAPSHOT_URL = 'http://127.0.0.1:3000/snapshot';
-const DEFAULT_FETCH_TIMEOUT_MS = 5_000;
 const MAX_FIELD_LEN = 120;
 
-const args = parseArgs({
-  options: {
-    interval: {
-      type: 'string',
-      short: 'i',
-      default: DEFAULT_INTERVAL_MS
-    },
-    url: {
-      type: 'string',
-      short: 'u',
-      default: DEFAULT_SNAPSHOT_URL
-    },
-    timeout: {
-      type: 'string',
-      short: 't',
-      default: String(DEFAULT_FETCH_TIMEOUT_MS)
-    }
-  },
-  allowPositionals: true
-});
+function parseDashboardArgs() {
+  try {
+    return parseArgs({
+      options: {
+        interval: { type: 'string', short: 'i' },
+        url: { type: 'string', short: 'u' },
+        timeout: { type: 'string', short: 't' },
+        once: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+      },
+      allowPositionals: true,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message.split('. ')[0] : String(err);
+    process.stderr.write(`ark-dashboard: ${message}. Run ark-dashboard --help.\n`);
+    process.exit(2);
+  }
+}
+
+const args = parseDashboardArgs();
+if (args.values.help || args.positionals[0] === 'help') {
+  console.log(DASHBOARD_HELP);
+  process.exit(0);
+}
+if (args.values.version) {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
 
-const parsedInterval = parseInt(args.values.interval, 10);
-const interval =
-  Number.isFinite(parsedInterval) && parsedInterval >= 200 && parsedInterval <= 60_000
-    ? parsedInterval
-    : Number(DEFAULT_INTERVAL_MS);
-const targetUrl = args.values.url || DEFAULT_SNAPSHOT_URL;
-const parsedTimeout = parseInt(args.values.timeout, 10);
-const fetchTimeoutMs =
-  Number.isFinite(parsedTimeout) && parsedTimeout >= 200 && parsedTimeout <= 60_000
-    ? parsedTimeout
-    : DEFAULT_FETCH_TIMEOUT_MS;
+const envUrl = process.env.ARK_DASHBOARD_URL?.trim();
+const urlExplicit = Boolean(args.values.url || envUrl);
+const targetUrl = args.values.url || envUrl || DASHBOARD_DEFAULT_URL;
+const interval = clampDashboardMs(args.values.interval, DASHBOARD_DEFAULT_INTERVAL_MS);
+const fetchTimeoutMs = clampDashboardMs(args.values.timeout, DASHBOARD_DEFAULT_TIMEOUT_MS);
+const once = Boolean(args.values.once);
 
 const RESET = '\x1b[0m';
 const RED = '\x1b[31m';
@@ -73,22 +85,6 @@ function sanitizeField(value, maxLen = MAX_FIELD_LEN) {
   return text;
 }
 
-function siblingUrl(snapshotUrl, suffix) {
-  try {
-    const u = new URL(snapshotUrl);
-    let basePath = u.pathname;
-    if (basePath.endsWith('/snapshot')) {
-      basePath = basePath.slice(0, -'/snapshot'.length);
-    } else if (basePath.endsWith('/snapshot/')) {
-      basePath = basePath.slice(0, -'/snapshot/'.length);
-    }
-    u.pathname = `${basePath}${suffix}`;
-    return u.toString();
-  } catch {
-    return null;
-  }
-}
-
 /**
  * @returns {{ ok: true, data: unknown } | { ok: false, kind: 'waiting' | 'failure', error?: string }}
  */
@@ -340,6 +336,7 @@ function renderHardening(snapshotResult) {
     } else {
       const detail = snapshotResult.error ? ` (${snapshotResult.error})` : '';
       console.log(`${RED}Failure contacting kernel${detail}${RESET}`);
+      if (!urlExplicit) console.log(`${MUTED}${DASHBOARD_EPHEMERAL_PORT_HINT}${RESET}`);
     }
     return;
   }
@@ -381,13 +378,13 @@ function renderHardening(snapshotResult) {
 }
 
 async function render() {
-  process.stdout.write('\x1b[2J\x1b[H');
+  if (!once) process.stdout.write('\x1b[2J\x1b[H');
   console.log(`ArkGate Observability Dashboard`);
   console.log(`Time: ${sanitizeField(new Date().toISOString())}`);
   console.log(`Endpoint: ${sanitizeField(targetUrl)}\n`);
 
-  const outboxUrl = siblingUrl(targetUrl, '/outbox');
-  const workflowsUrl = siblingUrl(targetUrl, '/workflows');
+  const outboxUrl = dashboardSiblingUrl(targetUrl, '/outbox');
+  const workflowsUrl = dashboardSiblingUrl(targetUrl, '/workflows');
   const [snapshotResult, outboxResult, workflowsResult] = await Promise.all([
     fetchJsonResult(targetUrl),
     fetchJsonResult(outboxUrl),
@@ -404,9 +401,15 @@ async function render() {
     snapshot?.outbox,
     snapshot?.workflows,
   );
+  return snapshotResult.ok;
 }
 
 async function startDashboard() {
+  if (once) {
+    const ok = await render();
+    process.exitCode = ok ? 0 : 1;
+    return;
+  }
   console.log(
     `Starting ArkGate Observability Dashboard (polling every ${interval}ms, fetch timeout ${fetchTimeoutMs}ms)`,
   );