@aitne-sh/aitne 0.1.8 → 0.1.10

package/agent-assets/templates/{rules → policies}/journal-format.md

@@ -22,7 +22,7 @@ because the human user doesn't journal by hand — but the perspective,
 voice, and content all belong to the user.
 
 Agent-side bookkeeping (action counts, internal anomalies, audit
-trail) lives in `agent/journal.md` — not here. If you find yourself
+trail) lives in `journal/agent.md` — not here. If you find yourself
 about to log "the agent ran N tools today" or "the hourly check
 fired M times", that belongs in the agent-side log instead. Filter
 it out.
@@ -108,7 +108,7 @@ day, etc.
 **Sections deliberately NOT in the daily journal:**
 
 - ❌ Agent action counts (`agent_actions` breakdown by type). Lives
-  in `agent/journal.md` instead — the audit-trail footprint.
+  in `journal/agent.md` instead — the audit-trail footprint.
 - ❌ Internal stage status, retry counts, anomalies. Same as above.
 - ❌ "The agent did X for the user" framing. The user's diary uses
   user voice; agent meta-narration belongs in the agent-side log.
@@ -129,7 +129,7 @@ day, etc.
 
 - When `settings.vault_mode` is `obsidian`, Stage B renders project /
   people references throughout the body as `[[wikilinks]]` targeting
-  `projects/<slug>.md` or `user/people.md#<person>` (basename resolves
+  `projects/<slug>.md` or `identity/people.md#<person>` (basename resolves
   automatically). The `## Summary` paragraph is the primary surface,
   but data sections may also receive wikilinks where a project / person
   name appears (e.g. a meeting title containing a person's name).
@@ -140,10 +140,10 @@ day, etc.
 
 ## Redaction
 
-- Apply `rules/redaction.md` patterns to the entire body Stage B
+- Apply `policies/redaction.md` patterns to the entire body Stage B
   authors (Summary + data sections both — Stage B owns the body, so
   redaction applies wherever sensitive content might surface).
-- Apply `rules/journal-export.md` user rules to the entire body.
+- Apply `policies/journal-export.md` user rules to the entire body.
 - If yesterday.md frontmatter had `no_journal_export: true`, write
   `[Skipped by user request]` as the body of `## Summary` and omit
   the data sections (they would echo information the export rule is

package/agent-assets/templates/{rules/policies → policies/management-captures}/_index.md

@@ -8,8 +8,8 @@ template_version: 2
 
 Auto-maintained by the daemon's policy-index reconciler. Direct edits
 are overwritten on the next reconcile pass — to add or modify a policy,
-edit its `rules/policies/<slug>.md` file (or use the `management-policy`
-skill).
+edit its `policies/management-captures/<slug>.md` file (or use the
+`management-policy` skill).
 
 ## Active
 

package/agent-assets/templates/{rules → policies}/management.md

@@ -32,15 +32,15 @@ or the dashboard's Settings → Management page._
 ## C. Active Policies
 
 Auto-maintained by the daemon (do not edit). Source files live under
-`rules/policies/<slug>.md`; capture new policies via the
-`management-policy` skill. Full index: [[rules/policies/_index.md]]
+`policies/management-captures/<slug>.md`; capture new policies via the
+`management-policy` skill. Full index: [[policies/management-captures/_index.md]]
 
 _No active policies yet._
 
 ## Notes
 
 - The agent cannot use `Edit` / `Write` tools on this file — writes go
-  through `/api/context/rules/management` (locked + snapshotted) or the
+  through `/api/context/policies/management` (locked + snapshotted) or the
   managed-tasks / sot-bindings API surfaces.
 - This file is injected into every flow via `policy-files.ts`. Keep it
   concise so prompt assembly stays cheap.

package/agent-assets/templates/{rules → policies}/mcp.md

@@ -16,7 +16,7 @@ This file governs how the agent uses attached Model Context Protocol
   the target with me via DM when the change is visible to others (a new
   issue, a posted message, an edited doc).
 - Failures are loggable events. On repeated MCP call failures, the agent
-  appends to `agent/journal.md` and surfaces the pattern at the next
+  appends to `journal/agent.md` and surfaces the pattern at the next
   hourly check.
 - Scope to the active task. MCP calls unrelated to the current flow's
   stated goal are skipped.

package/agent-assets/templates/{rules → policies}/redaction.md

@@ -22,7 +22,7 @@ redaction is performed in code by `packages/shared/src/secret-redaction.ts`.
 ## Context-specific (journal export)
 
 When exporting `daily/*.md` to an external vault (B-005), additional
-user-defined rules in `rules/journal-export.md` are applied on top.
+user-defined rules in `policies/journal-export.md` are applied on top.
 
 ## Appearance in logs
 

package/agent-assets/templates/{routines → policies/routines}/_index.md

@@ -17,4 +17,4 @@ I've added later via DM). All checks are treated equally.
 | `evening.md` | evening | `routine.evening_review` |
 | `weekly.md` | Friday | `routine.weekly_review` |
 | `monthly.md` | month-end | `routine.monthly_review` |
-| custom/<slug>.md | user-defined cron in `routines/custom/` | `routine.custom.<slug>` |
+| custom/<slug>.md | user-defined cron in `policies/routines/custom/` | `routine.custom.<slug>` |

package/agent-assets/templates/{routines → policies/routines}/evening.md

@@ -10,7 +10,7 @@ template_version: 1
 ## Checks
 
 ### Today → Handoff
-- **Action**: scan `today.md` for open items and summarize them into
+- **Action**: scan `state/today.md` for open items and summarize them into
   `## Handoff` so tomorrow's morning routine can pick them up
 
 ### Tomorrow preview
@@ -18,5 +18,5 @@ template_version: 1
   deadlines into `## Handoff`
 
 ### Journal tail
-- **Action**: append a 1–2 sentence note to `agent/journal.md` describing
+- **Action**: append a 1–2 sentence note to `journal/agent.md` describing
   anything surprising the agent observed today

package/agent-assets/templates/{routines → policies/routines}/hourly.md

@@ -21,7 +21,7 @@ skipping any whose preconditions are not met.
 
 ### Upcoming schedule
 - **Precondition**: always
-- **Action**: scan `today.md` `## Agent Plan` for items in the next 60
+- **Action**: scan `state/today.md` `## Agent Plan` for items in the next 60
   min; ensure each has a `scheduled.task` row.
 
 ## Skip conditions (applied before any check)

package/agent-assets/templates/{routines → policies/routines}/monthly.md

@@ -17,9 +17,9 @@ Fires on the last calendar day of the month. Output target:
   `daily/*.md` items
 
 ### Roadmap delta
-- **Action**: compare current `roadmap.md` against the month's progress;
+- **Action**: compare current `plans/roadmap.md` against the month's progress;
   highlight completed + delayed items
 
 ### Habit + health snapshot
-- **Action**: if the user logged health/habit data in `user/personal.md`,
+- **Action**: if the user logged health/habit data in `identity/personal.md`,
   surface month-over-month changes (opt-in only)

package/bin/aitne.mjs

@@ -8,6 +8,21 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { ensureBuild } from "../scripts/run-node.mjs";
 import { fetchHttpOk, openBrowser } from "../scripts/browser.mjs";
+// Port defaults live in this plain-ESM module (NOT @aitne/shared, per the
+// pre-build constraint noted below). scripts/lib/ ships in the published
+// `files` list, so this import works in global installs too.
+import {
+  DEFAULT_API_PORT,
+  DEFAULT_DASHBOARD_PORT,
+  resolveApiPort,
+  resolveDashboardPort,
+} from "../scripts/lib/ports.mjs";
+import {
+  classifyPid,
+  parsePidMeta,
+  readProcessStartToken,
+  serializePidMeta,
+} from "../scripts/lib/process-identity.mjs";
 
 const IS_WINDOWS = process.platform === "win32";
 
@@ -55,8 +70,8 @@ const DAEMON_PID_FILE = path.join(PIDS_DIR, "daemon.pid");
 const DASHBOARD_PID_FILE = path.join(PIDS_DIR, "dashboard.pid");
 const DAEMON_LOG_FILE = path.join(DATA_DIR, "logs", "daemon.log");
 const DASHBOARD_LOG_FILE = path.join(DATA_DIR, "logs", "dashboard.log");
-const DAEMON_PORT = parseInt(process.env.PA_API_PORT || "8321", 10);
-const DASHBOARD_PORT = parseInt(process.env.PA_DASHBOARD_PORT || "3000", 10);
+const DAEMON_PORT = resolveApiPort();
+const DASHBOARD_PORT = resolveDashboardPort();
 
 const VERSION = JSON.parse(
   fs.readFileSync(path.join(PROJECT_ROOT, "package.json"), "utf8"),
@@ -89,18 +104,25 @@ function rotateLogFile(logFile) {
   try { fs.renameSync(logFile, rotated); } catch { /* ignore */ }
 }
 
-function readPid(pidFile) {
+function readPidMeta(pidFile) {
   try {
-    const content = fs.readFileSync(pidFile, "utf8").trim();
-    const pid = parseInt(content, 10);
-    return Number.isFinite(pid) ? pid : null;
+    return parsePidMeta(fs.readFileSync(pidFile, "utf8"));
   } catch {
     return null;
   }
 }
 
+/**
+ * Persist the PID plus a start-identity token so a later `start`/`stop`/`status`
+ * can tell *our* process from a recycled PID after an unclean shutdown. Line 1
+ * stays the bare PID so an older aitne still reads the file. If the OS
+ * start-time read fails we write just the bare PID and degrade to the legacy
+ * unverified-but-trusted behavior. See process-lifecycle-2 in
+ * CROSS_PLATFORM_REAUDIT_2026-06.md.
+ */
 function writePid(pidFile, pid) {
-  fs.writeFileSync(pidFile, String(pid) + "\n");
+  const startToken = readProcessStartToken(pid);
+  fs.writeFileSync(pidFile, serializePidMeta({ pid, startToken }));
 }
 
 function removePid(pidFile) {
@@ -177,11 +199,25 @@ function nextSpawnArgs(dashboardDir, nextBin, userArgs) {
   return userArgs;
 }
 
+/**
+ * Resolve the live PID recorded in `pidFile`, or null. This is the single
+ * chokepoint every command (start/stop/status, plus open/uninstall/doctor via
+ * ctx.helpers) funnels through, so identity reconciliation here fixes them all
+ * at once. A recycled PID (start-time token mismatch) classifies `stale` → the
+ * pidfile is removed and null returned, so `start` won't false-"Already
+ * running" and `stop` won't kill an unrelated tree. `running-unverified`
+ * (legacy file with no token, or an OS start-time read failure) degrades to the
+ * pre-fix bare-PID behavior — no regression; a legacy file self-heals on the
+ * next writePid. verifyStartup() deliberately does NOT route through here: it
+ * checks the freshly-spawned in-memory pid via isAlive + health, preserving its
+ * "alive but health not responding = hung" branch.
+ */
 function getRunningPid(pidFile) {
-  const pid = readPid(pidFile);
-  if (pid == null) return null;
-  if (!isAlive(pid)) { removePid(pidFile); return null; }
-  return pid;
+  const meta = readPidMeta(pidFile);
+  if (!meta || meta.pid == null) return null;
+  const verdict = classifyPid(meta, { readToken: readProcessStartToken, isAlive });
+  if (verdict === "stale") { removePid(pidFile); return null; }
+  return meta.pid;
 }
 
 /**
@@ -305,7 +341,14 @@ async function cmdLogRunner(args) {
     }
   };
 
-  const child = spawn(spec.command, spec.args, {
+  // Under shell:true on Windows, cmd.exe re-parses the line and does NOT
+  // auto-quote the command, so a spaced install path (C:\\Users\\First Last\\...)
+  // would split at the space. Double-quote the command so it stays one token.
+  // POSIX is byte-identical: spec.shell is never true off Windows (the `.cmd`
+  // predicate at the call site is gated on IS_WINDOWS). Args here are static
+  // literals (start --port <n>) with no metacharacters, so they need no escaping.
+  const runCommand = spec.shell === true ? `"${spec.command}"` : spec.command;
+  const child = spawn(runCommand, spec.args, {
     cwd: spec.cwd,
     env: process.env,
     stdio: ["ignore", "pipe", "pipe"],
@@ -418,7 +461,7 @@ async function cmdStart(args = []) {
   // cmd.exe and are kept only as a last fallback.
   const nextBin = resolveNextBin(dashboardDir);
   const dashArgs = nextSpawnArgs(dashboardDir, nextBin, [
-    "start", "--port", String(DASHBOARD_PORT),
+    "start", "--port", String(DASHBOARD_PORT), "--hostname", "127.0.0.1",
   ]);
   const dashboard = spawnLoggedService({
     command: nextBin,
@@ -1004,8 +1047,8 @@ Options:
 
 Environment:
   PA_DATA_DIR                       Data directory (default: ~/.personal-agent)
-  PA_API_PORT                       Daemon port (default: 8321)
-  PA_DASHBOARD_PORT                 Dashboard port (default: 3000)
+  PA_API_PORT                       Daemon port (default: ${DEFAULT_API_PORT})
+  PA_DASHBOARD_PORT                 Dashboard port (default: ${DEFAULT_DASHBOARD_PORT})
 
 Examples:
   aitne start                       Launch in background

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitne-sh/aitne",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Aitne — a local-first, proactive personal AI agent. A long-running TypeScript daemon is the nervous system; Claude Code (or Codex / Gemini CLI) is the brain. All persistent memory lives in local Markdown files.",
   "keywords": [
     "ai",
@@ -43,9 +43,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@aitne/daemon": "0.1.8",
-    "@aitne/dashboard": "0.1.8",
-    "@aitne/shared": "0.1.8"
+    "@aitne/daemon": "0.1.10",
+    "@aitne/dashboard": "0.1.10",
+    "@aitne/shared": "0.1.10"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.58.1",
@@ -75,6 +75,7 @@
     "test": "node scripts/check-redaction-coverage.mjs && vitest run --coverage",
     "test:watch": "vitest",
     "check:redaction": "node scripts/check-redaction-coverage.mjs",
+    "check:vault-paths": "node scripts/check-vault-path-drift.mjs",
     "lint": "turbo run lint",
     "typecheck:tests": "turbo run typecheck:tests",
     "clean": "turbo run clean && node scripts/rm-paths.mjs node_modules .buildstamp"

package/scripts/commands/doctor.mjs

@@ -12,7 +12,9 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import net from "node:net";
+import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 export async function run(args, ctx) {
   if (args.includes("--help") || args.includes("-h")) {
@@ -38,7 +40,7 @@ Exit code:
     await checkSecretStore(ctx),
     await checkBackendCli(),
     await checkProcessProbe(),
-    await checkBrowserOpener(),
+    await checkBrowserOpener(ctx.DASHBOARD_PORT),
     await checkDataDirWritable(ctx.DATA_DIR),
     await checkBetterSqlite3(ctx.PROJECT_ROOT),
     await checkAgentAssets(ctx.PROJECT_ROOT),
@@ -127,8 +129,8 @@ async function checkPort(label, port, pidFile, getRunningPid) {
     label,
     detail: `${port} in use by another process`,
     hint: label.startsWith("Daemon")
-      ? `Set PA_API_PORT to an open port (e.g. PA_API_PORT=8322 aitne start), or stop the conflicting process.`
-      : `Set PA_DASHBOARD_PORT to an open port (e.g. PA_DASHBOARD_PORT=3001 aitne start), or stop the conflicting process.`,
+      ? `Set PA_API_PORT to an open port (e.g. PA_API_PORT=8331 aitne start), or stop the conflicting process.`
+      : `Set PA_DASHBOARD_PORT to an open port (e.g. PA_DASHBOARD_PORT=8333 aitne start), or stop the conflicting process.`,
   };
 }
 
@@ -164,7 +166,13 @@ async function checkSecretStore(ctx) {
       return { status: "pass", label: "Secret store", detail: "libsecret (`secret-tool`) reachable" };
     } catch {
       const hasMaster = !!process.env.PA_MASTER_PASSWORD;
-      const keyfile = path.join(ctx.DATA_DIR, "secrets", ".master-key");
+      // The daemon's secret clients hardcode ~/.personal-agent/secrets and do
+      // NOT honor PA_DATA_DIR (secret-client-file.ts:99,209 — homedir-hardcoded;
+      // createSecretClient passes no dir). Probe the same homedir-anchored path
+      // so this diagnostic agrees with where keys are actually read. If the
+      // daemon is ever changed to honor PA_DATA_DIR for secrets, revert this and
+      // fix at the factory (secret-client-factory.ts) instead.
+      const keyfile = path.join(os.homedir(), ".personal-agent", "secrets", ".master-key");
       const hasKeyfile = fs.existsSync(keyfile);
       if (hasMaster || hasKeyfile) {
         return {
@@ -182,11 +190,17 @@ async function checkSecretStore(ctx) {
     }
   }
   if (platform === "win32") {
-    const psBinary = whichSync("powershell.exe") ? "powershell.exe" : "pwsh.exe";
+    // Match the factory's terminal fallback (secret-client-factory.ts:37-41): prefer
+    // in-box powershell.exe, else pwsh.exe, else default to powershell.exe — the exact
+    // binary the daemon will exec — so a both-missing FAIL names the right binary.
+    const psBinary = whichSync("powershell.exe") ? "powershell.exe" : (whichSync("pwsh.exe") ? "pwsh.exe" : "powershell.exe");
     try {
+      // Mirror WindowsDpapiSecretClient's real encrypt path: ConvertTo/From-SecureString
+      // (no -Key => DPAPI). Works on both powershell.exe (5.1) and pwsh.exe (7+); the prior
+      // [ProtectedData] type check false-fails on PowerShell-Core-only hosts that work fine.
       execFileSync(psBinary, [
-        "-NoProfile", "-Command",
-        "[System.Security.Cryptography.ProtectedData] | Out-Null; exit 0",
+        "-NoProfile", "-NonInteractive", "-Command",
+        "$s = ConvertTo-SecureString 'probe' -AsPlainText -Force; $e = ConvertFrom-SecureString $s; if (-not $e) { exit 1 }; exit 0",
       ], { stdio: "pipe", timeout: 5000 });
       return { status: "pass", label: "Secret store", detail: `Windows DPAPI via ${psBinary} reachable` };
     } catch (err) {
@@ -253,7 +267,7 @@ async function checkProcessProbe() {
  * Warn-only: nothing in the daemon depends on this; users can navigate to
  * the dashboard URL by hand if missing.
  */
-async function checkBrowserOpener() {
+async function checkBrowserOpener(dashboardPort) {
   const platform = process.platform;
   const tool =
     platform === "darwin" ? "open"
@@ -268,7 +282,7 @@ async function checkBrowserOpener() {
     detail: `${tool} not on PATH`,
     hint:
       platform === "linux"
-        ? "apt install xdg-utils  · or open http://localhost:3000 manually after `aitne start`."
+        ? `apt install xdg-utils  · or open http://localhost:${dashboardPort} manually after \`aitne start\`.`
         : "Auto-open is a convenience; the dashboard URL works in any browser.",
   };
 }
@@ -365,7 +379,8 @@ async function checkRepositoryGithubLinkDrift(dataDir) {
         },
       ];
     }
-    Database = (await import(found)).default ?? (await import(found));
+    const mod = await import(pathToFileURL(found).href);
+    Database = mod.default ?? mod;
   } catch (err) {
     return [
       {

package/scripts/commands/run-now.mjs

@@ -9,8 +9,10 @@
  *     `docs/design/appendices/evening-review-slimdown.md` §2.2.
  *
  * Implementation:
- *   - Reads the daemon's apiToken from the macOS Keychain (the same
- *     entry the dashboard proxy uses). Bearer-auth required because
+ *   - Reads the daemon's apiToken from the OS secret store (macOS
+ *     Keychain, Windows DPAPI, Linux libsecret, or the encrypted file
+ *     fallback) via the shared cross-platform reader — the same entry
+ *     the dashboard proxy uses. Bearer-auth required because
  *     `POST /api/agent/run-now/*` routes are Approve-tier in the
  *     `risk-classifier`.
  *   - POSTs to `http://127.0.0.1:<PA_API_PORT>/api/agent/run-now/<job>`.
@@ -23,7 +25,7 @@
  *   - 3  daemon not running, not reachable, or 5xx
  *   - 4  result.status === "failed" — the job reported errors[]
  */
-import { execFileSync } from "node:child_process";
+import { readApiToken } from "../lib/read-api-token.mjs";
 
 const SUPPORTED_JOBS = new Set(["roadmap_maintenance"]);
 
@@ -53,7 +55,7 @@ export async function run(args, ctx) {
   const token = readApiToken();
   if (!token) {
     process.stderr.write(
-      "Failed to read daemon API token from the macOS Keychain.\n" +
+      "Failed to read the daemon API token from the OS secret store.\n" +
         "Is the daemon initialized? Run `aitne start` once first.\n",
     );
     process.exit(3);
@@ -125,23 +127,6 @@ function parseArgs(args) {
   return opts;
 }
 
-function readApiToken() {
-  try {
-    return execFileSync(
-      "security",
-      [
-        "find-generic-password",
-        "-s",
-        "com.personal-agent.secret.apiToken",
-        "-w",
-      ],
-      { encoding: "utf-8" },
-    ).trim();
-  } catch {
-    return null;
-  }
-}
-
 function printSummary(job, result) {
   if (job === "roadmap_maintenance") {
     if (!result || typeof result !== "object") {

package/scripts/lib/ports.d.mts

@@ -0,0 +1,27 @@
+/**
+ * Type declarations for the plain-ESM launcher mirror `ports.mjs`.
+ *
+ * `ports.mjs` is hand-written JavaScript (it must run before the TypeScript
+ * build), so it carries no inferred types. This sidecar lets TypeScript
+ * consumers — notably the `packages/shared/src/ports.test.ts` drift guard,
+ * which imports this module to assert it stays in lockstep with the TS
+ * source-of-truth `packages/shared/src/ports.ts` — typecheck the import under
+ * `strict`. Keep these signatures identical to `ports.ts`'s exports (minus
+ * `loopbackOrigins`, which is TS-only and not mirrored here).
+ */
+
+/** Daemon HTTP API port. Overridable via `PA_API_PORT`. */
+export const DEFAULT_API_PORT: number;
+
+/** Dashboard (Next.js) port. Overridable via `PA_DASHBOARD_PORT`. */
+export const DEFAULT_DASHBOARD_PORT: number;
+
+/** Resolve the daemon API port from env, falling back to DEFAULT_API_PORT. */
+export function resolveApiPort(
+  env?: Record<string, string | undefined>,
+): number;
+
+/** Resolve the dashboard port from env, falling back to DEFAULT_DASHBOARD_PORT. */
+export function resolveDashboardPort(
+  env?: Record<string, string | undefined>,
+): number;

package/scripts/lib/ports.mjs

@@ -0,0 +1,36 @@
+/**
+ * Default network ports for the Aitne daemon API and dashboard.
+ *
+ * SINGLE SOURCE OF TRUTH (launcher / plain-ESM side). `bin/aitne.mjs` and the
+ * `scripts/**` launchers cannot import `@aitne/shared`: they run *before* the
+ * TypeScript build that produces it (running `aitne start` is what triggers
+ * that build), and the published package ships only `bin` + `scripts/*.mjs` +
+ * `agent-assets`, never `packages/`. So the defaults are mirrored here in a
+ * build-independent module that lives under the published `scripts/lib/`.
+ *
+ * The TypeScript mirror lives in `packages/shared/src/ports.ts`. The two are
+ * pinned together by `packages/shared/src/ports.test.ts`, which fails CI if
+ * the values ever drift. Change a default in BOTH or the test goes red.
+ */
+
+/** Daemon HTTP API port. Overridable via `PA_API_PORT`. */
+export const DEFAULT_API_PORT = 8321;
+
+/** Dashboard (Next.js) port. Overridable via `PA_DASHBOARD_PORT`. Not 3000 — that collides with most dev servers. */
+export const DEFAULT_DASHBOARD_PORT = 8322;
+
+function parsePort(raw) {
+  if (raw == null || raw === "") return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/** Resolve the daemon API port from env, falling back to DEFAULT_API_PORT. */
+export function resolveApiPort(env = process.env) {
+  return parsePort(env.PA_API_PORT) ?? DEFAULT_API_PORT;
+}
+
+/** Resolve the dashboard port from env, falling back to DEFAULT_DASHBOARD_PORT. */
+export function resolveDashboardPort(env = process.env) {
+  return parsePort(env.PA_DASHBOARD_PORT) ?? DEFAULT_DASHBOARD_PORT;
+}

package/scripts/lib/process-identity.d.mts

@@ -0,0 +1,46 @@
+/**
+ * Type declarations for the plain-ESM launcher module `process-identity.mjs`.
+ *
+ * `process-identity.mjs` is hand-written JavaScript (it must run before the
+ * TypeScript build, from `bin/aitne.mjs`), so it carries no inferred types.
+ * This sidecar lets the `packages/shared/src/process-identity.test.ts` peer
+ * test typecheck the import under `strict`. Mirrors the `ports.d.mts`
+ * precedent. Keep these signatures in lockstep with the `.mjs` exports.
+ */
+
+/** Parsed pidfile contents. `startToken` is null for a legacy (tokenless) file. */
+export interface PidMeta {
+  pid: number;
+  startToken: string | null;
+}
+
+/** Injectable OS shims for {@link readProcessStartToken} (tests only). */
+export interface ReadTokenDeps {
+  platform?: NodeJS.Platform;
+  execFileSync?: (command: string, args?: readonly string[], options?: unknown) => string | Buffer;
+  readFileSync?: (path: string, encoding: string) => string;
+}
+
+/** Liveness + start-time reader injected into {@link classifyPid}. */
+export interface ClassifyDeps {
+  readToken: (pid: number) => string | null;
+  isAlive: (pid: number) => boolean;
+}
+
+export type PidClassification = "stale" | "running-ours" | "running-unverified";
+
+export function serializePidMeta(input: { pid: number; startToken?: string | null }): string;
+
+export function parsePidMeta(content: string): PidMeta | null;
+
+export function parseLinuxStat(statContent: string): string | null;
+
+export function readProcessStartToken(
+  pid: number | null | undefined,
+  deps?: ReadTokenDeps,
+): string | null;
+
+export function classifyPid(
+  meta: { pid?: number | null; startToken?: string | null } | null | undefined,
+  deps: ClassifyDeps,
+): PidClassification;