portable-agent-layer 0.69.0 → 0.71.0

package/README.md

@@ -87,8 +87,11 @@ pal cli status        # check your setup
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
+| `pal cli telos` | Which TELOS topics are answered, in interview order, and which one comes next |
+| `pal cli timezone [<zone>]` | Show or set your timezone. IANA names only, validated before it is stored |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
+| `pal cli server` | The morning screen: a local page to open before a terminal — three moves for today, an urgent/important grid over every project *and* every stated goal, where you left off, and a drawer holding the signal and the action ledger — `start [--port <n>]`, `stop`, `status`. Loopback only, default port 7250. No model runs on page load |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |
@@ -184,6 +187,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `frontend-design` | Build production-grade frontend interfaces |
 | `fyzz-chat-api` | Query Fyzz Chat conversations via API |
 | `humanize` | Rewrite text to strip AI tells and read as human |
+| `onboarding` | Interview the user to fill empty TELOS topics and the timezone, one topic at a time |
 | `opinion` | Confirm or contradict tracked opinions (confidence-weighted) |
 | `pal-analyze` | Surface rating trends, failure patterns, and graduation candidates |
 | `pal-reflect` | Promote recurring observations into tracked opinions |
@@ -222,6 +226,7 @@ Your setup should be able to travel with you.
 - **Cross-agent**: full support for Claude Code, opencode, Cursor, GitHub Copilot, and Codex (Codex still lacks subagents)
 - **Subscription-first inference**: background inference routes through whichever subscription CLI is active — no API key needed by default
 - **Portable knowledge**: export and import accumulated knowledge
+- **A morning screen, not a dashboard**: `pal cli server` ranks your projects *and* your written goals in one urgent/important grid. Urgency is read off the files — blockers, an unfinished handoff, a date in a next step, an important thing gone quiet. Importance comes from one fact per project: whether it serves a goal you wrote down, is a way the work could pay, or is kept for its own sake. PAL guesses that once at session stop; you correct it on the page or with `project.ts serves <name> goal|revenue|fun`, and the correction survives every later guess
 - **TypeScript-first**: built in TypeScript from day one
 - **Open source**: hackable, inspectable, extensible
 - **Composable**: intended to fit into real developer workflows

package/assets/schema/pal-settings.schema.json

@@ -69,6 +69,10 @@
           "type": "boolean",
           "description": "Prompt-time \"Potential matching skills\" hints, matched from each skill's metadata.triggers."
         },
+        "wallClock": {
+          "type": "boolean",
+          "description": "One line of the current time with every prompt, in identity.principal.timezone, so a session resumed hours later knows the day changed."
+        },
         "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
       }
     },

package/assets/skills/onboarding/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: onboarding
+license: MIT
+description: "Interview the user to fill in the personal context PAL has none of: their TELOS topics, one per pass, and their timezone. Use when the user wants to set up or flesh out that context: onboard me, fill in my telos, interview me about my goals, PAL doesn't know anything about me, help me write my mission, what should PAL know about me."
+argument-hint: "[topic to start with]"
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "onboarding"
+    - "onboard me"
+    - "fill in my telos"
+    - "set up my telos"
+    - "interview me about my goals"
+    - "personal context is empty"
+    - "you don't know anything about me"
+    - "help me write my mission"
+---
+
+Fill the personal context by asking, one topic per pass, and write only what the user actually said.
+
+TELOS is the context that orients every future session: purpose, goals, obstacles, methods, principles. The timezone is what makes "this morning" mean anything. A fresh install ships the TELOS files as empty scaffolds and guesses the timezone from the machine, and both stay that way until someone asks. This skill is that asking. It is deliberately not part of install: a user who has just installed a tool cannot yet say what they want from it, and answers given under that pressure are worse than no answers.
+
+## Ask the CLI what is missing
+
+```bash
+pal cli telos
+```
+
+It prints every topic as answered or unanswered, in interview order, and names the next unanswered one. That command owns the definition of "unanswered" — a scaffold of headings and empty bullets is not an answer. Do not open the files to judge for yourself, and do not restate the rule here: one definition, in one place, is the point.
+
+Read a file only when you need the format of an existing entry, or when the user asks what is already on record.
+
+## Workflow
+
+1. Run `pal cli telos`.
+
+2. Pick this pass's topic:
+   - The user named one in the argument → use it, answered or not.
+   - Otherwise → the `next:` topic the command printed.
+   - `next: none` → say so, list what is on file in one line each, and offer the optional topics. Do not re-interview an answered topic unless asked.
+
+   | File | The question behind it |
+   |------|------------------------|
+   | `MISSION.md` | What are you actually doing with your working life? |
+   | `GOALS.md` | What are you working toward, by when? |
+   | `CHALLENGES.md` | What is in the way right now? |
+   | `STRATEGIES.md` | How do you approach work and decisions? |
+   | `BELIEFS.md` | What principles do you refuse to trade away? |
+   | `MODELS.md` `NARRATIVES.md` `LEARNED.md` `IDEAS.md` | Optional, on request only |
+
+3. Open the topic with one sentence saying why the answer changes how you behave in future sessions, then ask **one** question. Never ask two questions in one turn, and never present a numbered list of questions to work through.
+
+4. Follow up until the answer is specific enough to act on. A usable answer names something concrete: a company, a role, a date, an amount, a named obstacle. A vague answer ("grow professionally", "be healthier") gets one follow-up asking for the concrete version. Stop after two follow-ups on the same point whether or not it got sharper.
+
+5. Draft the entry in the file's existing format, show it, and ask for a yes before writing. The draft may only contain what the user said in this conversation. If they went quiet on part of it, that part is absent from the draft, not filled in by you.
+
+6. Write it with the telos tool, never by editing the file:
+
+   ```bash
+   bun ~/.pal/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
+   ```
+
+   `<FILE>` is the bare filename, `<description>` is a short line naming what the entry covers and the date it was given.
+
+7. Report what landed, name the next unanswered topic, and stop. One topic per invocation. The user resumes by invoking the skill again, whenever that is.
+
+## The timezone
+
+Check it on the first pass only:
+
+```bash
+pal cli timezone                    # show what is configured
+pal cli timezone Europe/Budapest    # set it, IANA names only
+```
+
+Install prefills it from the machine, so it is usually already right and usually not worth a question. Ask only when it reads as not set, or when the user has corrected you about the date or the hour in this session. Settings are hook-protected, so this command is the only way to change it — never edit `pal-settings.json`.
+
+## Never invent an answer
+
+The whole value of this context is that it is the user's own words. An invented goal is worse than an empty file, because every later session treats it as fact and ranks work against it.
+
+- Do not draft an answer from the repository, the user's projects, their git history, or anything you inferred earlier in the session.
+- Do not offer a filled-in answer for confirmation. "Is your mission to build a small consultancy?" invites a yes that was yours, not theirs.
+- You may offer two or three short examples of the *kind* of answer the question wants, clearly marked as examples from nobody in particular, when the user is stuck.
+- "I don't know" is a valid answer. Say the topic stays open, write nothing, and move to the next one.
+- If the user's answer contradicts what is already on file, show both and ask which holds. Do not merge them silently.
+
+## Output format
+
+Conversational, not a form. Per pass:
+
+- One line on why this topic matters to future sessions.
+- One question, then a real exchange.
+- A drafted entry shown before writing, and an explicit request to confirm.
+- After writing: one line confirming the file, and one line naming the next unanswered topic.
+
+## When to use
+
+- The user asks to be onboarded or interviewed, or to fill in, set up, or flesh out their personal context.
+- The user says PAL knows nothing about them, or asks what it should know.
+- A task needs personal context (ranking work, weighing a decision) and `pal cli telos` reports the relevant topic unanswered. Offer this skill; do not start the interview uninvited.
+
+## Do NOT use
+
+- To read, view, or summarize existing TELOS content, or to record a single stated change to it — that is the `telos` skill.
+- To act on a timezone the user simply states ("we moved to Berlin") — run `pal cli timezone` and move on. No interview.
+- To record an observation about the user made during other work — that is a relationship note.
+- To set the assistant's name or the startup catchphrase — that is identity, and `pal cli init` asks for it.
+- To fill several topics in one pass because the user seems willing. One topic per invocation is the design; long forms produce shallow answers.

package/assets/skills/projects/SKILL.md

@@ -38,7 +38,8 @@ Output is JSON.
 | Command | Purpose |
 |---------|---------|
 | `list` | All registered projects with status, path, updated, stale flag, and counts |
-| `create [name] [--path PATH] [--objectives "a;b;c"]` | Register a project. Defaults: name=basename(cwd), path=cwd. Slug must be `[a-z0-9_-]+` |
+| `create [name] [--path PATH] [--objectives "a;b;c"] [--serves KIND] [--serves-note "..."]` | Register a project. Defaults: name=basename(cwd), path=cwd. Slug must be `[a-z0-9_-]+`. KIND is `goal`, `revenue` or `fun` |
+| `serves <name> <goal\|revenue\|fun> [note]` | Set what the project is for, after the fact |
 | `resume <name>` | Print the full project ISA — all frontmatter and body sections |
 | `add-next <name> "text"` | Append a next step (array, instantly appendable) |
 | `add-blocker <name> "text"` | Append a blocker (array, instantly appendable) |
@@ -94,6 +95,7 @@ When SessionStart context flags the current cwd as unregistered (e.g. `💡 cwd
 - **Default name** = the FULL last path segment of cwd, lowercased. For `/repos/portable-agent-layer` → `portable-agent-layer`. Never split on `-`.
 - **Confirm before creating.** Never auto-create without explicit user approval ("yes", "do it", "register").
 - **Capture context in conversation.** If the user accepts but doesn't volunteer a goal, ask one short question, or infer from the last few messages and confirm.
+- **Ask what it serves.** One question, at registration: is this moving a stated goal forward, a way the work could pay, or kept for its own sake? Pass the answer as `--serves goal|revenue|fun` with a six-word `--serves-note`. It is the only thing that ranks the project against the others, and PAL will guess it later if you skip it — a guess the user then has to correct.
 
 ### When NOT to suggest registration
 
@@ -120,7 +122,14 @@ User: "store under <project> that a reference implementation exists in this repo
 ```
 User: "track this project"
 → Default name from cwd basename, confirm with user
-→ bun ~/.pal/tools/project.ts create --path "$(pwd)" --objectives "first objective; second objective"
+→ Ask what it serves: a goal, a way it could pay, or fun
+→ bun ~/.pal/tools/project.ts create --path "$(pwd)" --objectives "first objective; second objective" --serves revenue --serves-note "could be sold as a service"
+```
+
+**Correcting what a project is for**
+```
+User: "<project> isn't a toy, it's the thing I'd actually sell"
+→ bun ~/.pal/tools/project.ts serves <slug> revenue "the one I would sell"
 ```
 
 **Logging a decision**

package/assets/templates/pal-settings.json

@@ -28,6 +28,7 @@
     "selfModel": true,
     "contextualSteering": true,
     "skillMatching": true,
+    "wallClock": true,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -83,6 +83,8 @@
     "@types/adm-zip": "^0.5.8",
     "@types/bun": "latest",
     "@types/node": "latest",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
     "husky": "^9.1.7",
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
@@ -100,6 +102,8 @@
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
     "playwright": "^1.60.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "unpdf": "^0.12.0"
   }
 }

package/src/cli/index.ts

@@ -17,6 +17,7 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
+ *   server start|stop|status          The control room, a local page over ~/.pal
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
@@ -47,7 +48,7 @@ import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
 import { ensureRegistered, writeRegistryEntry } from "../hooks/lib/machine";
 import { palHome, palPkg, paths, platform } from "../hooks/lib/paths";
 import { auditBindings, describeBindingIssue } from "../hooks/lib/projects";
-import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
+import { telosStatus } from "../hooks/lib/telos-topics";
 import { log } from "../targets/lib";
 import { checkPendingMigrations } from "./migrate";
 
@@ -239,6 +240,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "server": {
+      const { runServer } = await import("./server");
+      const code = await runServer(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "subagent": {
       const { runSubagent } = await import("./subagent");
       const code = await runSubagent(args);
@@ -258,6 +265,18 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "telos": {
+      const { runTelos } = await import("./personal-context");
+      const code = runTelos(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
+    case "timezone": {
+      const { runTimezone } = await import("./personal-context");
+      const code = runTimezone(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "debug":
       cliDebug(args);
       break;
@@ -284,6 +303,19 @@ function banner() {
   console.log("");
 }
 
+/**
+ * Install asks for identity and stops. TELOS is a conversation, not a form: a
+ * user who has just installed a tool cannot yet say what they want from it, and
+ * answers given under that pressure are worse than none.
+ */
+function pointAtOnboarding(): void {
+  const unanswered = telosStatus().filter((topic) => topic.priority && !topic.answered);
+  if (unanswered.length === 0) return;
+  log.info(
+    `PAL knows nothing about you yet (${unanswered.length} topics open). When you have half an hour, ask your agent to onboard you.`
+  );
+}
+
 function showHelp() {
   console.log(`
   Usage:
@@ -304,10 +336,13 @@ function showHelp() {
     pal cli usage                           Summarize token usage and cost
     pal cli actor [label <name>]            Show or rename this actor (who caused a record)
     pal cli machine [label <name>]          Show or rename this install (where it was written)
+    pal cli telos                           Which TELOS topics are answered, in interview order
+    pal cli timezone [<zone>]               Show or set your timezone (IANA name)
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
                                             e.g. ledger log --project X --since 7d
+    pal cli server start|stop|status        The control room: a local page to open before a terminal
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent
@@ -863,15 +898,16 @@ function doctor(silent = false): DoctorResult {
         : fail("CLAUDE.md — missing (run 'pal cli install --claude')");
     }
 
-    // Setup state — check file content directly (no setup.json dependency)
+    // An empty TELOS is a normal state, not a broken install: the onboarding
+    // skill fills it whenever the user is ready, which may be months from now.
     {
-      const missing = STEP_ORDER.filter(
-        (key) => !hasRealContent(resolve(home, SETUP_STEPS[key].file))
-      );
-      missing.length === 0
-        ? ok("TELOS setup complete")
+      const unanswered = telosStatus(home)
+        .filter((topic) => topic.priority && !topic.answered)
+        .map((topic) => topic.key);
+      unanswered.length === 0
+        ? ok("TELOS answered")
         : warn(
-            `TELOS setup incomplete — ${missing.join(", ")} missing (run 'pal cli install')`
+            `TELOS unanswered — ${unanswered.join(", ")} (ask your agent to onboard you)`
           );
     }
 
@@ -1193,13 +1229,12 @@ async function install(targets: Targets) {
   const { scaffoldTelos, scaffoldPalSettings, copyPalDocs, generateSkillIndex } =
     await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
-  const { promptTelos } = await import("./setup-telos");
   const { promptAttribution } = await import("./setup-attribution");
   scaffoldTelos();
   scaffoldPalSettings();
   await promptIdentity();
-  await promptTelos();
   await promptAttribution();
+  pointAtOnboarding();
 
   // Registers the label loadActor derives, so it travels on the next export.
   const { ensureActorRegistered } = await import("../hooks/lib/actor");

package/src/cli/ledger.ts

@@ -16,6 +16,7 @@ import type { LedgerEntry } from "../hooks/lib/ledger";
 import {
   type ChainVerdict,
   chainVerdict,
+  changedLines,
   changeShape,
   findEntry,
   type LedgerFilter,
@@ -145,23 +146,6 @@ function shortId(id: string): string {
   return id.slice(0, 11).padEnd(11);
 }
 
-function changedLines(entry: LedgerEntry): string {
-  const shape = changeShape(entry);
-  switch (shape.kind) {
-    case "redacted":
-      return "withheld";
-    case "truncated":
-      return "too large";
-    case "none":
-      return "no change";
-    default: {
-      const added = shape.delta.hunks.reduce((n, h) => n + h.insert.length, 0);
-      const removed = shape.delta.hunks.reduce((n, h) => n + h.remove, 0);
-      return `+${added} -${removed}`;
-    }
-  }
-}
-
 function cmdLog(args: string[]): number {
   const parsed = parseFilters(args);
   if (typeof parsed === "string") return fail(parsed);

package/src/cli/personal-context.ts

@@ -0,0 +1,67 @@
+/**
+ * pal cli telos / pal cli timezone — the personal context PAL carries about you.
+ *
+ *   pal cli telos             Which TELOS topics are answered, in interview order
+ *   pal cli timezone          Show the configured timezone
+ *   pal cli timezone <zone>   Set it, if Intl recognises the name
+ *
+ * Both exist for the onboarding skill. pal-settings.json is hook-protected, so
+ * an agent cannot write the timezone itself, and a skill that restated the
+ * answered/unanswered rule in prose would drift from the code that decides it.
+ */
+
+import {
+  identity,
+  raw as readSettings,
+  write as writeSettings,
+} from "../hooks/lib/settings";
+import { telosStatus } from "../hooks/lib/telos-topics";
+import { canonicalTimeZone } from "../hooks/lib/wall-clock";
+import { log } from "../targets/lib";
+
+export function runTelos(args: string[]): number {
+  if (args.length > 0) {
+    log.error(`Unknown telos argument: ${args[0]}`);
+    log.info("Usage: pal cli telos");
+    return 1;
+  }
+
+  const topics = telosStatus();
+  for (const topic of topics) {
+    const mark = topic.answered ? "answered " : "unanswered";
+    const tier = topic.priority ? "" : "  (optional)";
+    console.log(`  ${mark}  ${topic.key.padEnd(11)} ${topic.file}${tier}`);
+  }
+
+  const next = topics.find((topic) => topic.priority && !topic.answered);
+  console.log("");
+  console.log(next ? `next: ${next.key}` : "next: none — every priority topic answered");
+  return 0;
+}
+
+export function runTimezone(args: string[]): number {
+  const requested = args.join(" ").trim();
+
+  if (!requested) {
+    const current = identity().principal.timezone;
+    console.log(
+      current ? `timezone: ${current}` : "timezone: not set — times read as UTC"
+    );
+    return 0;
+  }
+
+  const zone = canonicalTimeZone(requested);
+  if (!zone) {
+    log.error(`Not a timezone Intl recognises: ${requested}`);
+    log.info("Use an IANA name — Europe/Budapest, America/New_York, Asia/Tokyo");
+    return 1;
+  }
+
+  const settings = { ...readSettings() };
+  settings.identity ??= {};
+  settings.identity.principal ??= {};
+  settings.identity.principal.timezone = zone;
+  writeSettings(settings);
+  log.success(`timezone: ${zone}`);
+  return 0;
+}

package/src/cli/server.ts

@@ -0,0 +1,201 @@
+/**
+ * pal cli server — start, stop and inspect the local control room.
+ *
+ * The server itself is src/tools/control-room/server.ts, run detached so it
+ * outlives the shell that started it. This file only owns the lifecycle:
+ * spawning, waiting for it to answer, remembering its pid, and killing it.
+ */
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { spawnDetachedInference } from "../hooks/lib/detached-inference";
+import { paths } from "../hooks/lib/paths";
+import { DEFAULT_PORT, LOOPBACK, type ServerStatus } from "../tools/control-room/server";
+
+interface ServerState {
+  pid: number;
+  port: number;
+  startedAt: string;
+}
+
+const SERVER_SCRIPT = resolve(
+  import.meta.dir,
+  "..",
+  "tools",
+  "control-room",
+  "server.ts"
+);
+const STARTUP_TIMEOUT_MS = 3000;
+const PROBE_TIMEOUT_MS = 500;
+
+export async function runServer(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "start":
+      return cmdStart(rest);
+    case "stop":
+      return cmdStop();
+    case "status":
+      return cmdStatus();
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      showHelp();
+      return 0;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      showHelp();
+      return 1;
+  }
+}
+
+function showHelp(): void {
+  console.log(`
+  Usage:
+    pal cli server <subcommand>
+
+  Subcommands:
+    start [--port <n>]         Start the control room in the background (default port ${DEFAULT_PORT})
+    stop                       Stop it
+    status                     Show whether it is running, and where
+
+  The page listens on ${LOOPBACK} only.
+`);
+}
+
+function url(port: number): string {
+  return `http://${LOOPBACK}:${port}/`;
+}
+
+function readState(): ServerState | null {
+  const file = paths.serverState();
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as ServerState;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state: ServerState): void {
+  writeFileSync(paths.serverState(), JSON.stringify(state, null, 2), "utf-8");
+}
+
+function clearState(): void {
+  const file = paths.serverState();
+  if (existsSync(file)) unlinkSync(file);
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function probe(port: number): Promise<ServerStatus | null> {
+  try {
+    const res = await fetch(`${url(port)}api/status`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    return res.ok ? ((await res.json()) as ServerStatus) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function waitUntilAnswering(port: number): Promise<ServerStatus | null> {
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const status = await probe(port);
+    if (status) return status;
+    await Bun.sleep(100);
+  }
+  return null;
+}
+
+function parsePort(args: string[]): number | string {
+  const { values } = parseArgs({ args, options: { port: { type: "string" } } });
+  if (values.port === undefined) return DEFAULT_PORT;
+  const port = Number(values.port);
+  return Number.isInteger(port) && port > 0 && port < 65536
+    ? port
+    : `--port must be a port number, got ${values.port}`;
+}
+
+async function cmdStart(args: string[]): Promise<number> {
+  const port = parsePort(args);
+  if (typeof port === "string") return fail(port);
+
+  const running = await runningServer();
+  if (running) {
+    console.log(`Already running at ${url(running.port)} (pid ${running.pid})`);
+    return 0;
+  }
+
+  spawnDetachedInference(SERVER_SCRIPT, [`--port=${port}`], "control-room");
+  const status = await waitUntilAnswering(port);
+  if (!status)
+    return fail(
+      `The control room did not answer on port ${port} within ${STARTUP_TIMEOUT_MS / 1000}s. Is the port free?`
+    );
+
+  writeState({ pid: status.pid, port, startedAt: status.startedAt });
+  console.log(url(port));
+  return 0;
+}
+
+/** The state file is a claim; the process answering on that port is the fact. */
+async function runningServer(): Promise<ServerState | null> {
+  const state = readState();
+  if (!state || !alive(state.pid)) return null;
+  return (await probe(state.port)) ? state : null;
+}
+
+async function cmdStop(): Promise<number> {
+  const state = readState();
+  if (!state) {
+    console.log("Not running.");
+    return 0;
+  }
+  if (alive(state.pid)) {
+    process.kill(state.pid);
+    console.log(`Stopped pid ${state.pid}.`);
+  } else {
+    console.log(`Pid ${state.pid} was already gone; cleared the stale record.`);
+  }
+  clearState();
+  return 0;
+}
+
+async function cmdStatus(): Promise<number> {
+  const state = readState();
+  if (!state) {
+    console.log("Not running.");
+    return 1;
+  }
+  const status = alive(state.pid) ? await probe(state.port) : null;
+  if (!status) {
+    console.log(
+      `Not running (stale record for pid ${state.pid}; run \`pal cli server stop\`).`
+    );
+    return 1;
+  }
+  console.log(`
+  ${url(status.port)}
+  pid          ${status.pid}
+  started      ${status.startedAt}
+  ledger       ${status.ledgerFiles} file(s)
+  machine      ${status.machine}
+`);
+  return 0;
+}
+
+function fail(message: string): number {
+  console.error(message);
+  return 1;
+}

package/src/cli/setup-identity.ts

@@ -9,6 +9,17 @@ import {
   raw as readSettings,
   write as writeSettings,
 } from "../hooks/lib/settings";
+import { isValidTimeZone } from "../hooks/lib/wall-clock";
+
+/**
+ * Empty means the machine's guess, which clack substitutes after validation runs,
+ * so pressing Enter has to pass.
+ * @lintignore exercised directly by test/setup-identity.test.ts
+ */
+export function timezoneProblem(input: string | undefined): string | undefined {
+  if (!input || isValidTimeZone(input)) return undefined;
+  return `Not a timezone Intl recognises: ${input}`;
+}
 
 /** Prompt for missing identity fields. Skips any field that already has a value. */
 export async function promptIdentity(): Promise<void> {
@@ -80,8 +91,9 @@ export async function promptIdentity(): Promise<void> {
   if (needsTimezone) {
     const guess = Intl.DateTimeFormat().resolvedOptions().timeZone;
     const tz = await clack.text({
-      message: "Your timezone",
+      message: `Your timezone (Enter keeps ${guess})`,
       defaultValue: guess,
+      validate: timezoneProblem,
     });
     if (clack.isCancel(tz)) {
       clack.cancel("Setup cancelled");