@jmcombs/pi-steward 0.0.0

package/server/steward-config.ts

@@ -0,0 +1,430 @@
+/**
+ * Reads and validates the `steward.json` handshake artifact.
+ *
+ * `steward.json` is written by the `/steward_initialize` skill (a later phase),
+ * not by hand in the common case, and it drives Steward to run local commands —
+ * the host-metrics collector and the service-control commands — so it is a
+ * code-execution surface.
+ * This module is the gate in front of that. It reads the artifact from
+ * `STEWARD_CONFIG` (if set) else `~/.config/steward/steward.json`, and returns a
+ * typed config or `null` — it NEVER throws, because an absent, malformed, or
+ * untrusted config is a state to degrade on, not an error to crash the dashboard
+ * with.
+ *
+ * Security (plan §M7): before the config is trusted at all, its file must be
+ * owned by the current user and must not be world-writable — otherwise another
+ * user could drop a command in and have Steward run it. A separate per-command
+ * consent gate ({@link hostCollectorConsented}, {@link controlConsented}) then
+ * requires that exact command's hash to be present in the config's `consent`
+ * map, so a rewritten command re-prompts rather than riding an old blanket
+ * "yes".
+ *
+ * This module is Node-only (the server half): it touches the filesystem, the
+ * process uid, and `crypto`. It is never shipped to the browser.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ConsentDrift } from "../core/drift.js";
+import type { MemoryTopology, ServiceAction } from "../core/types.js";
+
+/** The environment variable that overrides the default config location. */
+const CONFIG_ENV = "STEWARD_CONFIG";
+
+/** The collector command + its cadence, as recorded in `steward.json`. */
+export interface HostCollectorConfig {
+  /** Argv of the long-lived collector: `command[0]` is the program, rest args. */
+  command: string[];
+  /** The collector's declared emit cadence, ms — the base for the staleness clock. */
+  intervalMs: number;
+}
+
+/**
+ * The service-control commands, as recorded in `steward.json`. All three are
+ * required together: a machine that can only be restarted is expressed by
+ * consenting to the restart command alone, not by declaring a partial block —
+ * that keeps "what this machine can do" (the argv) apart from "what the
+ * operator approved" (the consent map).
+ */
+export interface ServiceControlConfig {
+  start: string[];
+  stop: string[];
+  restart: string[];
+}
+
+/**
+ * What `/steward_initialize` observed about how `llama-server` is launched on
+ * this machine — the baseline the live process is re-checked against on every
+ * snapshot (see `server/drift-probe.ts`).
+ *
+ * It is a RECORD, not an instruction: Steward never launches anything from it
+ * and it carries no consent, which is why it needs no hash. `mechanism` and
+ * `label` are descriptive only (`launchd`, `gui/501/com.llamacpp.router`) and
+ * exist so a later phase can point the operator at the right file to fix.
+ */
+export interface LlamaLaunchConfig {
+  /** The argv the server was observed running with, `argv[0]` first. */
+  launchArgv: string[];
+  /** How it is launched (`launchd`, `systemd`, …), or `null` when unrecorded. */
+  mechanism: string | null;
+  /** The job/unit label, or `null` when unrecorded. */
+  label: string | null;
+}
+
+/**
+ * Where this machine's `llama-server` writes its combined stdout/stderr, as
+ * recorded by `/steward_initialize`.
+ *
+ * It is a path Steward READS, never a command it runs, so — unlike the collector
+ * and the control commands — it carries no consent hash: there is nothing here to
+ * approve. The file's ownership gate still applies, because it is the same file
+ * as everything else in this artifact.
+ */
+export interface LogFileConfig {
+  /** Absolute path to the log file to follow. */
+  path: string;
+}
+
+/**
+ * The slice of `steward.json` this phase reads. Unknown keys are ignored so the
+ * artifact can carry fields later phases own without this reader rejecting them.
+ */
+export interface StewardConfig {
+  /** Static machine memory layout — picks the HOST gauge SET, not a reading. */
+  memoryTopology: MemoryTopology;
+  /**
+   * Where `llama-server` listens, as the operator recorded it, or `null` when
+   * the artifact declares none.
+   *
+   * This **wins** over Pi's llama.cpp provider auth. It used to be written by
+   * setup and then ignored by this reader entirely, so a machine whose server
+   * was recorded on one port was polled on whatever port Pi's provider happened
+   * to name — the dashboard reported "not reachable" and every control looked
+   * broken while the server was healthy. Steward's own artifact is the operator
+   * telling Steward what to watch; the provider describes what Pi chats with,
+   * and the two are allowed to differ.
+   */
+  baseUrl: string | null;
+  hostCollector: HostCollectorConfig;
+  /**
+   * The recorded launch argv, or `null` when the artifact does not carry one
+   * (or carries an ill-formed one). Optional on purpose: drift re-validation is
+   * then simply unavailable — the dashboard says nothing about launch flags
+   * rather than refusing the whole config over a block nothing else depends on.
+   */
+  llama: LlamaLaunchConfig | null;
+  /**
+   * Start/stop/restart commands, or `null` when the artifact declares none (or
+   * declares them ill-formed). Control is optional: a machine may have metrics
+   * configured and no control, which is a dashboard state — a setup
+   * affordance — not a reason to reject the whole config.
+   */
+  control: ServiceControlConfig | null;
+  /**
+   * The log file to follow, or `null` when the artifact records none (or records
+   * an ill-formed one). Optional like the blocks above: a machine with no log
+   * path recorded still gets every other panel, and Steward falls back to
+   * `STEWARD_LOG_FILE` and the platform convention before giving up.
+   */
+  log: LogFileConfig | null;
+  /** sha256(command) → `true` for each command the operator has consented to run. */
+  consent: Record<string, true>;
+}
+
+/** The control actions, in the order the dashboard renders them. */
+const CONTROL_ACTIONS: readonly ServiceAction[] = ["start", "stop", "restart"];
+
+export interface ReadStewardConfigOptions {
+  /**
+   * Overrides the resolved config path (tests point this at a temp file). When
+   * omitted, `STEWARD_CONFIG` then `~/.config/steward/steward.json` is used.
+   */
+  path?: string;
+  /** The current uid, for the ownership check. Injected in tests; defaults to `process.getuid`. */
+  uid?: number | null;
+  /** Sink for the security warnings. Injected in tests; defaults to `console.warn`. */
+  warn?: (message: string) => void;
+}
+
+/** The path the config is read from, honouring `STEWARD_CONFIG`. */
+export function stewardConfigPath(): string {
+  const override = process.env[CONFIG_ENV];
+  if (override !== undefined && override.trim() !== "") return override;
+  return join(homedir(), ".config", "steward", "steward.json");
+}
+
+/** The current uid, or `null` on a platform without one (Windows). */
+function currentUid(): number | null {
+  return typeof process.getuid === "function" ? process.getuid() : null;
+}
+
+/**
+ * The canonical hash of a collector command, for the consent map: the sha256 of
+ * the argv joined on single spaces. The space join keeps the hash reproducible
+ * by hand (`printf '%s' 'macmon pipe -s 0 -i 1000' | shasum -a 256`) for a
+ * maintainer writing `steward.json` to test live; the `/steward_initialize`
+ * skill computes the same hash when it records consent. It trades a strict argv
+ * canonicalisation for that reproducibility — the gate's job is operator
+ * awareness of what runs, and consent still re-prompts whenever the command
+ * string changes.
+ */
+export function hashCommand(command: string[]): string {
+  return createHash("sha256").update(command.join(" ")).digest("hex");
+}
+
+/**
+ * True when the config's collector command carries a matching entry in the
+ * consent map. The collector must NOT be spawned otherwise: consent is bound to
+ * the exact command, so a rewritten or repo-dropped command falls through here
+ * and re-prompts (via the skill) rather than running under a stale approval.
+ */
+export function hostCollectorConsented(config: StewardConfig): boolean {
+  return config.consent[hashCommand(config.hostCollector.command)] === true;
+}
+
+/**
+ * True when the config declares a command for `action` AND that exact command
+ * carries a matching entry in the consent map. The same gate the collector
+ * passes through, applied per action: consenting to `restart` does not consent
+ * to `stop`, and rewriting a declared command drops it back out of the
+ * dashboard until the operator approves the new one.
+ */
+export function controlConsented(config: StewardConfig, action: ServiceAction): boolean {
+  if (config.control === null) return false;
+  return config.consent[hashCommand(config.control[action])] === true;
+}
+
+/**
+ * The control commands the operator has consented to, keyed by action — the
+ * exact set the executor is built from. An action that is declared but not
+ * consented is simply absent, so it is never offered and never runs.
+ */
+export function consentedControls(config: StewardConfig): Partial<Record<ServiceAction, string[]>> {
+  const commands: Partial<Record<ServiceAction, string[]>> = {};
+  if (config.control === null) return commands;
+  for (const action of CONTROL_ACTIONS) {
+    if (controlConsented(config, action)) commands[action] = [...config.control[action]];
+  }
+  return commands;
+}
+
+/**
+ * The commands this config declares but has NOT approved — the second producer
+ * of the dashboard's drift notice.
+ *
+ * A declared, unapproved command is Steward's security gate doing its job: the
+ * collector is not spawned, the button is not offered. But silence makes the
+ * resulting inert panel look identical to one that was never set up, and an
+ * operator who edited a command in `steward.json` (invalidating its hash) has no
+ * way to learn that is why their gauges went dark. This turns that into
+ * something the UI can say out loud.
+ */
+export function consentDrift(config: StewardConfig): ConsentDrift {
+  return {
+    hostCollector: !hostCollectorConsented(config),
+    controls:
+      config.control === null
+        ? []
+        : CONTROL_ACTIONS.filter((action) => !controlConsented(config, action)),
+  };
+}
+
+/** True for a non-null, non-array object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Validates the collector block, or `null` when it is missing/ill-formed. */
+function parseHostCollector(value: unknown): HostCollectorConfig | null {
+  if (!isRecord(value)) return null;
+  const { command, intervalMs } = value;
+  if (
+    !Array.isArray(command) ||
+    command.length === 0 ||
+    !command.every((part) => typeof part === "string")
+  ) {
+    return null;
+  }
+  if (typeof intervalMs !== "number" || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+    return null;
+  }
+  return { command: [...(command as string[])], intervalMs };
+}
+
+/** A non-empty argv of strings, or `null`. */
+function parseCommand(value: unknown): string[] | null {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  if (!value.every((part) => typeof part === "string")) return null;
+  return [...(value as string[])];
+}
+
+/** An optional descriptive string, trimmed, or `null` when absent/empty. */
+function parseLabel(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+/**
+ * Validates the optional `llama` block. Only `launchArgv` is load-bearing — it
+ * is the baseline the drift check diffs against — so a block without a usable
+ * one yields `null` (drift checking unavailable) rather than a half-recorded
+ * baseline that could report a mismatch against nothing.
+ */
+function parseLlama(value: unknown): LlamaLaunchConfig | null {
+  if (!isRecord(value)) return null;
+  const launchArgv = parseCommand(value.launchArgv);
+  if (launchArgv === null) return null;
+  return {
+    launchArgv,
+    mechanism: parseLabel(value.mechanism),
+    label: parseLabel(value.label),
+  };
+}
+
+/**
+ * Validates the optional `control` block. All three commands are required
+ * within it, so a half-written block yields `null` (control unconfigured)
+ * rather than a set of actions the operator never fully declared.
+ */
+function parseControl(value: unknown): ServiceControlConfig | null {
+  if (!isRecord(value)) return null;
+  const start = parseCommand(value.start);
+  const stop = parseCommand(value.stop);
+  const restart = parseCommand(value.restart);
+  if (start === null || stop === null || restart === null) return null;
+  return { start, stop, restart };
+}
+
+/**
+ * Validates the optional `log` block. Only a non-empty string path is usable;
+ * anything else yields `null` and the discovery precedence takes over, rather
+ * than handing the tailer a path it cannot watch.
+ */
+function parseLog(value: unknown): LogFileConfig | null {
+  if (!isRecord(value)) return null;
+  const path = parseLabel(value.path);
+  return path === null ? null : { path };
+}
+
+/** Validates the consent map, keeping only `true` entries. */
+function parseConsent(value: unknown): Record<string, true> {
+  if (!isRecord(value)) return {};
+  const consent: Record<string, true> = {};
+  for (const [key, granted] of Object.entries(value)) {
+    if (granted === true) consent[key] = true;
+  }
+  return consent;
+}
+
+/**
+ * Reads the config artifact, returning a validated {@link StewardConfig} or
+ * `null`. Returns `null` — quietly for a plain absence, with a warning for a
+ * refusal — when the file does not exist, cannot be read, is not owned by the
+ * current user, is world-writable, is not valid JSON, or fails schema
+ * validation. Never throws.
+ */
+export function readStewardConfig(options: ReadStewardConfigOptions = {}): StewardConfig | null {
+  const path = options.path ?? stewardConfigPath();
+  const uid = options.uid !== undefined ? options.uid : currentUid();
+  const warn = options.warn ?? ((message: string) => console.warn(message));
+
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(path);
+  } catch {
+    // Absent (or unreadable) is the normal cold-start case, not a warning.
+    return null;
+  }
+
+  // Ownership: a config owned by another user could have been planted; refuse
+  // it. Skipped only where the platform has no uid (Windows).
+  if (uid !== null && stat.uid !== uid) {
+    warn(`[steward] ignoring ${path}: not owned by the current user`);
+    return null;
+  }
+  // World-writable means anyone on the box can rewrite the command Steward runs.
+  if ((stat.mode & 0o002) !== 0) {
+    warn(`[steward] ignoring ${path}: it is world-writable`);
+    return null;
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    warn(`[steward] ignoring ${path}: it is not valid JSON`);
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    warn(`[steward] ignoring ${path}: it is not a JSON object`);
+    return null;
+  }
+
+  const memoryTopology = parsed.memoryTopology;
+  if (memoryTopology !== "unified" && memoryTopology !== "discrete") {
+    warn(`[steward] ignoring ${path}: memoryTopology must be "unified" or "discrete"`);
+    return null;
+  }
+
+  const hostCollector = parseHostCollector(parsed.hostCollector);
+  if (hostCollector === null) {
+    warn(`[steward] ignoring ${path}: hostCollector.command / intervalMs is missing or invalid`);
+    return null;
+  }
+
+  // Control is optional, and a present-but-ill-formed block is worth saying out
+  // loud: the operator meant to configure it and the dashboard will show the
+  // setup affordance instead, which is otherwise indistinguishable from having
+  // never configured it at all.
+  const control = parseControl(parsed.control);
+  if (parsed.control !== undefined && control === null) {
+    warn(`[steward] ${path}: ignoring control — it needs a start, stop and restart command`);
+  }
+
+  // The launch record is optional too, and losing it costs only the drift
+  // check — but silently, so a block that is present and unusable says so:
+  // otherwise the dashboard would look exactly like a compliant machine.
+  const llama = parseLlama(parsed.llama);
+  if (parsed.llama !== undefined && llama === null) {
+    warn(`[steward] ${path}: ignoring llama — it needs a non-empty launchArgv array of strings`);
+  }
+
+  // The log path is optional as well, and losing it costs only the console —
+  // but again, say so: a present-but-unusable block would otherwise look exactly
+  // like a machine that never recorded one.
+  const log = parseLog(parsed.log);
+  if (parsed.log !== undefined && log === null) {
+    warn(`[steward] ${path}: ignoring log — it needs a non-empty path string`);
+  }
+
+  // Optional like the blocks above, and said out loud when present but unusable:
+  // silently falling back to the provider's URL is exactly the failure this
+  // field exists to prevent.
+  const baseUrl =
+    typeof parsed.baseUrl === "string" && parsed.baseUrl.trim() !== ""
+      ? parsed.baseUrl.trim()
+      : null;
+  if (parsed.baseUrl !== undefined && baseUrl === null) {
+    warn(`[steward] ${path}: ignoring baseUrl — it needs a non-empty URL string`);
+  }
+
+  return {
+    memoryTopology,
+    baseUrl,
+    hostCollector,
+    llama,
+    control,
+    log,
+    consent: parseConsent(parsed.consent),
+  };
+}

package/setup/init-prompt.ts

@@ -0,0 +1,214 @@
+/**
+ * The `/steward_initialize` instructions.
+ *
+ * This used to be a skill — a `SKILL.md` with four reference files, ~770 lines
+ * of procedure and mechanism. It was replaced because the procedure turned out
+ * to be scaffolding a capable model supplies on its own: across live runs the
+ * model consistently detected, proposed and gated consent correctly without
+ * being told the shape of those steps, and the per-mechanism launchd/systemd
+ * recipes were describing a domain it already knows better than the prose did.
+ *
+ * What survives is the part a model cannot derive: the failures that leave a
+ * machine looking healthy. Each item under "What will lie to you" is a case
+ * where trying the obvious thing produces no error — an empty log on a running
+ * server, a 400 that means two different things, a consent hash mismatch that
+ * silently blanks the dashboard. A model self-corrects from a stack trace; it
+ * cannot self-correct from silence, so those are written down and the rest is
+ * not.
+ *
+ * It is delivered as a command rather than a prompt template because the helper
+ * script's absolute path is only known at runtime — the package can be
+ * installed anywhere — and templates substitute positional arguments only.
+ */
+
+import { join } from "node:path";
+
+/** Absolute path of the helper, resolved against this module's own location. */
+export function setupScriptPath(): string {
+  return join(import.meta.dirname, "steward-setup.mjs");
+}
+
+/**
+ * The instructions, with `scriptPath` written into the two commands that need
+ * it. Exported separately from the path so it can be tested without a real
+ * install layout.
+ */
+export function buildInitPrompt(scriptPath: string): string {
+  return `You are an expert at managing operating systems and services. Set this machine up so that
+**Steward** — a Pi plugin that runs a local dashboard for monitoring \`llama.cpp\` — can do its job.
+
+Find out what is true, tell me briefly, propose a plan, get my approval, carry it out, prove it
+worked. Detection is read-only. Nothing is applied without my approval.
+
+## How to report
+
+**Be brief.** No tables of evidence, no capability scorecards, no recap of the commands you ran.
+I want to read the answer, not the investigation. Two short sections:
+
+**Current state** — a handful of lines. What is running, what already works, what does not.
+**Plan** — a numbered list, one line per change, each with the exact command or diff. Mark any
+step that restarts the service or drops loaded models as **disruptive**.
+
+Then ask exactly one question: **approve the whole plan, or go one change at a time?**
+
+- If I approve the whole plan, carry it out end to end without stopping to re-ask. The plan told me
+  what was disruptive, so approving it is my consent for those steps too. Report once at the end.
+- If I ask to go one at a time, do that instead — one change, then stop.
+- Either way: if reality turns out differently from the plan mid-flight — a command fails, a file is
+  not what you expected, a step would now do something the plan did not describe — stop and tell me.
+  Approval covers the plan you showed me, not a different one.
+
+## First, learn the machine
+
+Nothing below names an operating system, a service manager, or a sensor tool, because you are
+better at recognising those than any list I could write. Establish them yourself before you propose
+anything:
+
+- **The OS and the hardware** — enough to know whether the GPU has its own memory or shares the
+  system's.
+- **How this machine supervises long-running services**, and how \`llama-server\` is started under it
+  today — the file or unit that defines it, the label it runs as, how it is stopped and reloaded. If
+  nothing supervises it, say so: that is the create path, and you write the definition.
+- **What can measure this host** — whichever tool is already installed for GPU, CPU and temperature.
+- **Where Pi already expects \`llama.cpp\`** — its provider's base URL. This is a *given*, not
+  something to negotiate: Pi is configured, other things may depend on it, and it holds that value
+  in memory for the life of the session. Read it before you plan anything.
+
+Say what you found in one line. Then translate every requirement below into that environment's own
+terms. The requirements are the contract; the mechanism is yours to choose.
+
+## What Steward needs to work
+
+It reads exactly one file, \`$STEWARD_CONFIG\` if set and non-empty, otherwise
+\`~/.config/steward/steward.json\`, and trusts nothing else about this machine. For each capability
+below, establish whether this machine already delivers it, and propose the smallest change if not.
+
+1. **A model catalogue, and load/unload.** \`llama-server\` must run in **router mode** — serving a
+   models directory and/or a preset file, with no \`-m\`/\`--model\`/\`-hf\`. Pi's llama.cpp provider
+   throws outright on a single-model server.
+2. **Throughput and request counters.** These come from llama.cpp's Prometheus \`/metrics\`, which is
+   **off by default**.
+3. **Per-slot context fill and the busy count.** From \`/slots\`, on unless disabled.
+4. **A log console.** One file containing the server's **complete** output — see the traps below.
+5. **The base URL Pi already expects.** Not a URL of your choosing — the one you found in
+   discovery. If \`llama-server\` is not answering there, **move the server to Pi's address**: change
+   the port in its service definition, reload, done. Do not move Pi to the server.
+
+   That direction matters. Editing Pi's provider config means editing a file Pi read once at
+   startup and now holds in memory, so the change does not take effect in the running session, may
+   live in more than one file, and can break other things pointing at the same provider. Moving the
+   server needs no Pi change at all, so nothing has to be reloaded and nothing can be half-applied.
+
+   If the server cannot move — the port is taken, or something else depends on it — say so and ask.
+   Do not finish with the two diverged: chat then fails with "llama.cpp unavailable" while Steward
+   reports a perfectly healthy router, which is worse than both being broken because nothing looks
+   wrong.
+6. **Host metrics.** Steward spawns one long-lived command you nominate and reads **NDJSON on its
+   stdout**, one object per line forever: \`{"schema":"steward.hostmetrics/1","ts":<epoch ms>,…}\`
+   with \`gpuUtil\`, \`cpuUtil\` as fractions 0..1, \`gpuTempC\`, \`cpuTempC\`, \`ramUsedGB\`, \`ramTotalGB\`.
+   Every field is \`number|null\`; \`null\` means "this machine cannot measure it" and is never a zero.
+   **Use the tool this machine already has before writing your own.** Whatever it is, it will
+   report figures a hand-rolled collector cannot reach — temperature in particular usually needs
+   privileged access or a vendor tool. Assembling one from general-purpose utilities works and
+   silently gives up those readings, leaving permanent no-reading gauges on a machine that could
+   have filled them. Check first; say which tool you found, or that you found none and what that
+   costs.
+7. **Start / stop / restart**, recorded as argv arrays. There is no shell: no pipes, no \`&&\`, no
+   \`~\`, no \`$UID\` — write absolute paths and real numbers.
+
+## Restarting the server can wedge Pi's connection
+
+Pi holds an open connection to \`llama.cpp\`. Restart the server underneath it and the next message
+can hang or fail with "Connection error" while the server answers \`curl\` perfectly. There is no
+reload for this.
+
+So if — and only if — you restarted the server, **end by saying that chat may need a nudge**, as the
+last line of your report:
+
+> The server was restarted. If chat does not respond, switch models once, or restart Pi.
+
+If you did not restart it, do not say this: a reconnect notice on a run that changed nothing reads
+as though something went wrong.
+
+## What will lie to you
+
+These are the failure modes you cannot detect by trying them, because each one leaves a machine
+that looks healthy. Everything else here you can verify yourself; these you cannot.
+
+- **\`--log-file\` corrupts the log in router mode.** It is a real, documented flag, which is why it
+  looks right. The router copies it into every child, each opens it truncate-not-append, and they
+  write at independent offsets. Never propose it.
+- **stdout alone gives you an empty log.** llama.cpp writes every levelled line — including every
+  error — to **stderr**, and only the forwarded child lines to **stdout**. Redirecting stdout only
+  yields a running server with a silent, often 0-byte log. Both streams must reach **one** file, however this
+  machine's service manager expresses that. Confirm it against the running process's file
+  descriptors, not only the launch record — the descriptors are the same question on every platform,
+  and they are the answer that cannot be stale.
+- **\`/metrics\`, \`/slots\` and \`/props\` return 400 both when the flag is missing and when no model is
+  loaded.** They cannot tell you whether the server is configured correctly. Determine compliance
+  from the **launch arguments**, never from a request.
+- **A hand-written consent hash fails silently.** Steward runs only commands whose sha256 it has
+  recorded; a mismatch produces no error, just dark gauges and missing buttons. Always derive it
+  with the helper below — never write that map yourself.
+- **Consent covers the argv, not the contents of whatever it points at.** Record the collector as a
+  self-contained command — \`["sh","-c","…pipeline…"]\` — never as a path to a script you wrote. A
+  recorded script path hashes only the path, so its contents can then change without invalidating
+  the consent, which is the entire point of the gate. A script file looks tidier and is a valid
+  argv array, which is exactly why this one is easy to get wrong.
+- **Restarting a service does not reload its definition.** Every service manager keeps the loaded
+  job separate from the file that describes it, and the restart verb usually acts on the loaded
+  copy: the process comes back with a new pid and exit 0, running the *old* definition, and nothing
+  in the output says so. Measured on one machine whose service file had gained \`--metrics\` and a
+  second redirect while the running process had neither and its log stayed at 0 bytes.
+  Find this machine's reload path and use it. Then **prove the change reached the process** — read
+  the live argv and the live file descriptors, not the file you edited. A restart that reports
+  success is not evidence.
+- **A stop that deregisters the service breaks Start.** Some managers have two kinds of stop: one
+  halts the process and leaves the job known, the other removes it entirely. Steward's Stop must be
+  the first kind, or Start has nothing left to start. Record the halting form, not the removing
+  one — and if reloading a definition requires the removing form, that is a separate step you
+  perform yourself, not the command you record.
+- **On unified-memory hardware there is no VRAM figure to report.** Where the GPU shares system
+  memory there is no separate pool and no readable ceiling, so record \`memoryTopology: "unified"\`
+  with RAM only. Any VRAM number there is invented. A discrete GPU is the other case, not the
+  default — decide from the hardware you found, not from the operating system.
+- **\`STEWARD_LOG_FILE\`, if set, overrides the log path you record.** Say which file the console will
+  actually follow. And prefer a durable location for the log over a temporary one: systems clear
+  their scratch directories on their own schedule, and a server stopped over a long weekend can come
+  back to find its history gone.
+
+## Writing the config
+
+Do not hand-write the artifact. Build a proposal — the same JSON without a \`consent\` map — and:
+
+\`\`\`
+node ${scriptPath} plan  --input ./proposal.json
+node ${scriptPath} apply --input ./proposal.json
+\`\`\`
+
+\`plan\` validates, derives the consent hashes and shows the diff without writing. \`apply\` backs up,
+writes atomically at mode 0600, and prints the revert command. Run \`help\` for the rest, including
+\`probe-collector\`, which runs a candidate collector and proves it really streams — do that before
+recording one.
+
+Proposal shape: \`memoryTopology\`, \`baseUrl\`, \`hostCollector{command,intervalMs}\`, \`log{path}\`,
+\`control{start,stop,restart}\`, \`llama{launchArgv,mechanism,label}\`.
+
+## Ground rules
+
+- **Name the disruption in the plan, not after it.** A restart drops every resident model and any
+  in-flight request — say so on the line that proposes it, so approving the plan is informed.
+- **Back up before editing, and tell me the exact revert command.** An exact command is one you
+  have checked will run on this machine in its current state — not a choice between two forms you
+  are unsure about. If you do not know which applies, find out before you offer it: a revert that
+  errors when I reach for it is worse than saying you don't know.
+  If a path is a symlink into a dotfiles repo, say so: the edit lands in version control.
+- **A missing setup is not damage.** If nothing is running and no service is defined, that is the
+  create path — build one and ask me for the directory and port. Never restore a deleted or
+  modified configuration from git, a backup, or shell history; that was someone's decision.
+- **Current state is what is on disk and running now.** Anything you learn from history, backups or
+  scratch files is inferred — label it, and never record it as this machine's configuration.
+- **Say what you could not establish** rather than guessing, and finish by telling me plainly what
+  is live and what is still missing.
+`;
+}

package/setup/steward-setup.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Types for the one helper the parity test imports directly.
+ *
+ * The script itself stays plain `.mjs` with only `node:` imports, so it runs on
+ * the oldest Node this package supports — older than default TypeScript
+ * stripping. That is why the drift comparison is duplicated there rather than
+ * imported from `core/drift.ts`, and why the parity test exists.
+ */
+
+export type RecordedArgvDiff =
+  | { status: "clean"; added: string[]; removed: string[]; program: string | null }
+  | { status: "drifted"; added: string[]; removed: string[]; program: string | null }
+  | { status: "unknown"; reason: string };
+
+/** Compares a recorded argv against a live `ps` line, as `core/drift.ts` does. */
+export function diffRecordedArgv(recorded: readonly string[], observed: string): RecordedArgvDiff;