@aitne-sh/aitne 0.1.9 → 0.1.11

package/scripts/lib/process-identity.mjs

@@ -0,0 +1,193 @@
+/**
+ * Process start-identity helpers for the Aitne launcher (`bin/aitne.mjs`).
+ *
+ * WHY THIS EXISTS — process-lifecycle-2 (CROSS_PLATFORM_REAUDIT_2026-06.md).
+ * The launcher trusts a bare PID: `process.kill(pid, 0)` is true for *any* live
+ * process owning that PID. After an unclean shutdown the stale `daemon.pid` /
+ * `dashboard.pid` can point at a PID the OS has recycled to an unrelated
+ * process, so `aitne start` false-positives "Already running" and `aitne stop`
+ * can `taskkill /T /F` (Windows) or group-kill (POSIX) the wrong process tree.
+ *
+ * FIX — pair the PID with the OS-reported process **start time**, captured at
+ * write time and re-read at check time. A recycled PID has a different start
+ * time, so an exact-string mismatch flags it stale. We compare the *same* OS
+ * field to *itself* on the *same* machine, so no absolute-time conversion,
+ * clock-skew tolerance, or locale handling is needed.
+ *
+ * WHERE THIS LIVES — `scripts/lib/` (plain ESM), because `bin/aitne.mjs` runs
+ * *before* the TypeScript build that produces `@aitne/shared` (running `aitne
+ * start` is what triggers that build) and the published package ships only
+ * `bin` + `scripts` + `agent-assets`. The pure functions here are pinned by a
+ * peer `.test.ts` under the daemon/shared `src` tree (the `ports.mjs`
+ * precedent), so they run under the standard vitest suite. The win32 read branch
+ * carries the usual "no Windows runtime validation" caveat; by construction it
+ * can only *degrade* to the legacy bare-PID behavior, never make things worse.
+ */
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import process from "node:process";
+
+/**
+ * Serialize PID metadata to the pidfile.
+ *
+ * Line 1 is the bare PID so an *older* aitne (which parses only line 1) still
+ * reads files written by this version — downgrade-safe. The identity token is
+ * written as a trailing `key=value` line (not positional) so a future field can
+ * be added without breaking parse order; {@link parsePidMeta} already ignores
+ * unknown keys. An absent token is omitted.
+ */
+export function serializePidMeta({ pid, startToken = null }) {
+  let out = `${pid}\n`;
+  if (startToken != null) {
+    const token = String(startToken).replace(/[\r\n]+/g, " ").trim();
+    if (token.length > 0) out += `start=${token}\n`;
+  }
+  return out;
+}
+
+/**
+ * Parse a pidfile written by {@link serializePidMeta} OR a legacy single-line
+ * (`<pid>\n`) file. Returns `null` if line 1 is not a finite integer. Unknown
+ * trailer keys are ignored, so the format stays forward-compatible.
+ */
+export function parsePidMeta(content) {
+  if (typeof content !== "string") return null;
+  const lines = content.split(/\r?\n/);
+  const pid = Number.parseInt((lines[0] ?? "").trim(), 10);
+  if (!Number.isFinite(pid)) return null;
+  let startToken = null;
+  for (const line of lines.slice(1)) {
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    const val = line.slice(eq + 1).trim();
+    if (key === "start") startToken = val.length > 0 ? val : null;
+  }
+  return { pid, startToken };
+}
+
+/**
+ * Extract field 22 (`starttime`, clock-ticks since boot) from `/proc/<pid>/stat`.
+ *
+ * The `comm` field (field 2) is wrapped in parens and may itself contain spaces
+ * and `)`, so the only safe split point is the LAST `)` — everything after it
+ * is space-separated starting at field 3 (state). field 22 is therefore index
+ * `22 - 3 = 19` in that tail. Boot-relative, so immune to wall-clock changes;
+ * across a reboot the recorded value's epoch is gone, which correctly reads as
+ * a mismatch (stale).
+ */
+export function parseLinuxStat(statContent) {
+  if (typeof statContent !== "string") return null;
+  const close = statContent.lastIndexOf(")");
+  if (close < 0) return null;
+  const fields = statContent.slice(close + 1).trim().split(/\s+/);
+  const starttime = fields[19];
+  return starttime && /^\d+$/.test(starttime) ? starttime : null;
+}
+
+/**
+ * Resolve the PowerShell executable on Windows. Prefer Windows PowerShell 5.1
+ * (`powershell.exe`), fall back to PowerShell 7+ (`pwsh.exe`) for minimal /
+ * Server-Core / pwsh-7-only hosts, else keep the default so a missing host
+ * surfaces a clear ENOENT. Mirrors `browser-history/lifecycle/platform.ts`.
+ */
+/* c8 ignore start -- win32-only path resolution; the POSIX test runner never enters this */
+function resolveWindowsPowerShell() {
+  const pathValue = process.env.PATH ?? "";
+  const exts = process.env.PATHEXT?.split(";").filter(Boolean) ?? [".EXE"];
+  const probe = (name) => {
+    const hasExt = /\.[A-Za-z0-9]+$/.test(name);
+    for (const dir of pathValue.split(delimiter)) {
+      if (!dir) continue;
+      const candidates = hasExt ? [name] : exts.map((e) => `${name}${e}`);
+      for (const c of candidates) {
+        try {
+          accessSync(join(dir, c), constants.X_OK);
+          return true;
+        } catch {
+          // keep scanning
+        }
+      }
+    }
+    return false;
+  };
+  return probe("powershell.exe") ? "powershell.exe" : probe("pwsh.exe") ? "pwsh.exe" : "powershell.exe";
+}
+/* c8 ignore stop */
+
+/**
+ * Read an opaque, OS-native start-time token for `pid`, or `null` if the PID is
+ * gone / the read fails. The token is compared *only* for exact-string equality
+ * against a token captured earlier for the same PID on the same machine, so its
+ * format is irrelevant as long as it is stable for a given process incarnation.
+ *
+ * `deps` is for testing — inject `platform` / `execFileSync` / `readFileSync`
+ * to exercise a branch off its native OS without touching the real system.
+ * Reads use `execFileSync` (never a shell) with a timeout; the PID is numeric,
+ * so there is no injection surface, but args stay arrayed on principle.
+ */
+export function readProcessStartToken(pid, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const exec = deps.execFileSync ?? execFileSync;
+  const readFile = deps.readFileSync ?? readFileSync;
+  if (pid == null || !Number.isFinite(Number(pid))) return null;
+  try {
+    if (platform === "linux") {
+      return parseLinuxStat(readFile(`/proc/${pid}/stat`, "utf8"));
+    }
+    if (platform === "darwin") {
+      const out = exec("ps", ["-o", "lstart=", "-p", String(pid)], {
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+        windowsHide: true,
+      });
+      const token = String(out).replace(/[\r\n]+/g, " ").trim();
+      return token.length > 0 ? token : null;
+    }
+    /* c8 ignore start -- win32-only; not reachable from the POSIX test runner */
+    if (platform === "win32") {
+      const ps = resolveWindowsPowerShell();
+      const out = exec(
+        ps,
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `(Get-Process -Id ${Number(pid)} -ErrorAction Stop).StartTime.ToString('o')`,
+        ],
+        { stdio: ["ignore", "pipe", "ignore"], timeout: 5_000, windowsHide: true },
+      );
+      const token = String(out).replace(/[\r\n]+/g, " ").trim();
+      return token.length > 0 ? token : null;
+    }
+    /* c8 ignore stop */
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify a pidfile's recorded process against the live system.
+ *
+ * - `stale`              — dead, or alive but the start-time token *differs*
+ *                          (PID recycled). Caller should remove the pidfile.
+ * - `running-ours`       — alive and the start-time token matches.
+ * - `running-unverified` — alive but identity can't be confirmed: a legacy file
+ *                          with no token, or the OS start-time read failed.
+ *                          Caller treats this as running (the pre-fix bare-PID
+ *                          behavior), so the change can never regress; a legacy
+ *                          file self-heals on the next `writePid`.
+ *
+ * `isAlive` / `readToken` are injected so the decision is pure and fully
+ * unit-testable without touching real processes.
+ */
+export function classifyPid(meta, { readToken, isAlive }) {
+  if (meta == null || meta.pid == null) return "stale";
+  if (!isAlive(meta.pid)) return "stale";
+  if (meta.startToken == null) return "running-unverified";
+  const live = readToken(meta.pid);
+  if (live == null) return "running-unverified";
+  return live === meta.startToken ? "running-ours" : "stale";
+}

package/scripts/lib/read-api-token.mjs

@@ -56,7 +56,7 @@ function readDarwin() {
     return execFileSync(
       "security",
       ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"],
-      { encoding: "utf-8" },
+      { encoding: "utf-8", timeout: 5_000 },
     ).trim();
   } catch {
     return null;

package/scripts/start.mjs

@@ -93,21 +93,31 @@ try {
 }
 const nextBin = resolveNextBin(dashboardDir);
 const dashArgs = nextSpawnArgs(dashboardDir, nextBin, [
-  "dev", "--port", String(DASHBOARD_PORT),
+  // Bind IPv4 loopback explicitly: with no --hostname, Next binds the
+  // unspecified IPv6 address `::`, and on Windows (IPV6_V6ONLY on) the
+  // 127.0.0.1 readiness probe in bin/aitne.mjs can't reach it. Match the
+  // probe and the daemon's 127.0.0.1-only posture. Byte-identical on
+  // macOS/Linux where the probe already reaches a `::`-bound socket.
+  "dev", "--port", String(DASHBOARD_PORT), "--hostname", "127.0.0.1",
 ]);
-const dashboard = spawn(nextBin, dashArgs, {
+const useShimShell = IS_WINDOWS && nextBin.toLowerCase().endsWith(".cmd");
+const dashCommand = useShimShell ? `"${nextBin}"` : nextBin;
+const dashboard = spawn(dashCommand, dashArgs, {
   cwd: dashboardDir,
   env: process.env,
   stdio: "inherit",
   windowsHide: true,
-  shell: IS_WINDOWS && nextBin.toLowerCase().endsWith(".cmd"),
+  shell: useShimShell,
 });
 children.push(dashboard);
 
 // ── 4. Auto-open browser ──
 
 if (!noOpen) {
-  const url = `http://localhost:${DASHBOARD_PORT}`;
+  // Match the dashboard's 127.0.0.1-only bind above. Using `localhost` here
+  // resolves to `::1` first on Windows, so both the readiness probe AND the
+  // browser open would miss the IPv4-only socket and time out.
+  const url = `http://127.0.0.1:${DASHBOARD_PORT}`;
   waitForHttpReady(url, {
     // `next dev` can take ~30s on a cold boot; give it headroom.
     timeoutMs: 60_000,

package/agent-assets/docs/features/routines/hourly-check.md

@@ -1,205 +0,0 @@
----
-schema_version: 1
-slug: features/routines/hourly-check
-title: Hourly Check
-id: hourly-check
-aliases:
-  - hourly
-  - observation consumer
-  - hourly check gate
-category: features
-summary: |
-  A medium-tier routine that fires every hour during active hours,
-  drains the pending observations queue, and decides whether the
-  accumulated change pattern warrants surfacing. Runs through a
-  four-layer gate that keeps quiet days quiet.
-section: routines
-tags:
-  - routines
-  - autonomous
-  - observations
-  - polling
-  - hourly-check
-status: stable
-ui_anchors:
-  - /settings/routines
-  - /settings/schedule
-  - /activity?tab=system
-ask_examples:
-  - What does the hourly check do?
-  - When does it run?
-  - How does the hourly check decide whether to escalate?
-  - What is the harvest pre-pass?
-  - How do I tune the gate's freshness window?
-locale: en-US
-created: 2026-04-25
-updated: 2026-05-28
-keywords:
-  - hourly
-  - observations
-  - polling
-  - hourly check
-  - gate
-  - layer 1
-  - layer 2
-  - layer 3
-  - harvestForGate
-  - decideStage
-  - pre-pass
-related:
-  - concepts/observations
-  - concepts/routines
-  - concepts/delegated-mode
-  - features/integrations/browser-history
-process_keys:
-  - routine.hourly_check
-  - routine.hourly_check.triage
-  - routine.fetch_window
-config_keys:
-  - hourlyCheckEnabled
-  - hourlyCheckIntervalMinutes
-  - hourlyCheckActiveStartHour
-  - hourlyCheckActiveEndHour
-  - hourlyCheckMinObservations
-  - hourlyCheckStage2Enabled
-  - hourlyCheckHeartbeatHours
-  - hourlyCheckLowSignalPendingCeiling
-  - hourlyCheckPrePassFreshnessMinutes
----
-
-# Hourly Check
-
-A medium-tier routine that drains the observations queue every hour
-during active hours and decides whether the accumulated change
-pattern warrants notifying you or appending to `state/today.md`. The
-"decide" step is a four-layer gate designed to keep quiet days quiet
-without missing the moment when something piles up.
-
-## When It Runs
-
-Every `hourlyCheckIntervalMinutes` (default 60), inside the active
-window `[hourlyCheckActiveStartHour, hourlyCheckActiveEndHour)`. The
-trigger:
-
-- **Skips** when the morning routine has not yet run today
-  (recoverable — the dispatcher enqueues a `queueMorningRoutineWake`
-  self-recovery and the hourly check resumes after the morning
-  routine succeeds).
-- **Skips** when another hourly check is in flight (atomic flag).
-- **Skips** when accumulated signal is below
-  `hourlyCheckMinObservations` and the heartbeat window
-  (`hourlyCheckHeartbeatHours`) hasn't elapsed.
-
-Every tick writes one `agent_actions` row with
-`action_type = 'hourly_check.gate'` so the gate's decisions are
-auditable from `aitne audit` and the dashboard activity feed.
-
-## The Four-Layer Gate
-
-The gate replaced the pre-Phase-9 "30-minute rate-limit" gate. It
-runs on every cron tick; only Layer 4 actually spawns a medium-tier
-agent session.
-
-### Layer 1 — Harvest pre-pass
-
-`HourlyCheckCoordinator.harvestForGate` spawns a lite-tier
-`routine.fetch_window` session for each delegated / native
-integration whose `runtime_state.pre_pass_last_run:<key>` is older
-than `hourlyCheckPrePassFreshnessMinutes`. The pre-pass fetches the
-integration's hourly window (mail / calendar / Notion) and POSTs the
-results to `/api/observations`, so the rest of the gate sees a
-populated queue instead of stale data.
-
-Telemetry: `agent_actions.detail.harvest_ran` /
-`harvest_integrations` / `harvest_failed_integrations`.
-
-### Layer 2 — Signal compute
-
-`computeHourlyCheckSignals` reads the observation table mode-blind —
-it filters by source-prefix sets derived from
-`INTEGRATION_DESCRIPTORS`, never by `actor`. Signal categories
-include unread-mail / event-change / repo-change / browser-history
-clusters; each category produces a (count, last-seen, summary)
-tuple. The pre-pass freshness gate from Layer 1 is what guarantees
-those counts reflect "now", not "an hour ago".
-
-### Layer 3 — Decide stage
-
-`decideStage` is a pure function over the signal snapshot plus the
-per-tick config (heartbeat status, `hourlyCheckStage2Enabled`,
-`hourlyCheckLowSignalPendingCeiling`). It returns one of three stages
-— `stage0_silent`, `stage2`, or `stage3`:
-
-| Stage | What happens |
-|---|---|
-| `stage0_silent` | No agent session. Consume the pending observations and append a single best-effort line to `state/today.md`'s `## Agent Log`. This is the verdict for both "no signals" and "low signal under the ceiling". |
-| `stage2` | Only reachable when `hourlyCheckStage2Enabled = true` (default `false`, so low-signal ticks fall through to `stage3`). Runs a lite-tier `routine.hourly_check.triage` call whose strict JSON output decides `log_only` (→ silent path) vs. `escalate` (→ `stage3`). |
-| `stage3` | Spawn the full medium-tier `routine.hourly_check` session — the visible agent run. Reached directly on high-novelty signals (VIP mail, calendar conflict, overdue agent plan, approaching schedule) or as the cautious default when Stage 2 is off. |
-
-When a Layer 1 pre-pass fails (`harvest.failed`), the gate
-short-circuits to a cautious `stage3` with reason
-`cautious_escalate_prepass_failure` and tags the audit row
-`agent_actions.detail.cautious_escalate = true` — a failed fetch
-should never silently swallow a tick's worth of signals.
-
-### Layer 4 — Dispatch
-
-When Layer 3 returns `stage0_silent` (or Stage 2 returns
-`log_only`), the daemon runs `runSilentHourlyCheckPath` — a
-daemon-direct write, no agent. When it returns `stage3` (or Stage 2
-returns `escalate`), `enqueueStage3HourlyCheck` puts a
-`routine.hourly_check` event on the bus, which becomes the visible
-agent session.
-
-## What It Outputs
-
-- A best-effort line in `state/today.md`'s `## Agent Log` — even the
-  silent path appends one (skipped only if `today.md` is missing or
-  the write lock is held; the observations are still consumed either
-  way).
-- Notifications when warranted (only on a `stage3` agent session).
-- An audit row on every tick:
-  `agent_actions.action_type = 'hourly_check.gate'`, carrying the
-  harvest + signal + stage detail.
-
-## Configuration
-
-| Setting | Default | Layer | Notes |
-|---|---|---|---|
-| `hourlyCheckEnabled` | `true` | trigger | Master kill switch. |
-| `hourlyCheckIntervalMinutes` | `60` | trigger | Cron cadence. |
-| `hourlyCheckActiveStartHour` | `4` | trigger | Active window start. |
-| `hourlyCheckActiveEndHour` | `24` | trigger | End-exclusive; `24` ≡ midnight. |
-| `hourlyCheckMinObservations` | `1` | trigger | Minimum pending observations before a non-silent stage dispatches; below this the tick records a `below_threshold` skip. |
-| `hourlyCheckPrePassFreshnessMinutes` | `30` | Layer 1 | Range `0`–`240`. Skip a per-integration fetch if its pre-pass ran more recently; `0` fetches every tick, `240` is cost-minimal. |
-| `hourlyCheckStage2Enabled` | `false` | Layer 3 | Adds the lite-tier triage call; while `false`, low-signal ticks route straight to `stage3`. |
-| `hourlyCheckHeartbeatHours` | `4` | Layer 3 | Range `1`–`48`. Force a non-silent stage at least this often, even on a quiet day. |
-| `hourlyCheckLowSignalPendingCeiling` | `0` | Layer 3 | Range `0`–`20`. At or below this pending count, a low-signal tick stays silent. `0` keeps the cautious default (any pending observation escalates). |
-
-(`hourlyCheckGateMode` was removed in HOURLY_CHECK_GATE_REDESIGN_PLAN
-Phase 4 — the gate has a single execution path now.)
-
-## When Something Goes Wrong
-
-- **Skipped because the morning routine hasn't run.** The
-  dispatcher's `morningRoutineRanToday` gate keys on
-  `agent_actions.result = 'success'`. The skip reason is
-  `morning_routine_pending_for_today` and triggers a
-  `queueMorningRoutineWake` self-recovery. See
-  [Morning Routine Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
-- **Stage 3 never fires on a quiet day.** Expected.
-  `hourlyCheckHeartbeatHours` forces a tick occasionally so silence
-  doesn't last indefinitely.
-- **Pre-pass keeps failing for one integration.** Read
-  `agent_actions.detail.harvest_failed_integrations`; the failing
-  integration name is recorded. Usually an auth issue — check
-  `/health.integrationModes` and the integration's settings page.
-
-## Related
-
-- [Observations](../../concepts/observations.md) — what populates the
-  queue Layer 2 reads.
-- [Delegated Mode](../../concepts/delegated-mode.md) — the
-  delegated / native integrations that participate in Layer 1's
-  harvest.
-- [Routines](../../concepts/routines.md)