opensquid 0.5.395

package/dist/runtime/paths.js

@@ -0,0 +1,303 @@
+/**
+ * Path resolution helpers for opensquid's filesystem layout.
+ *
+ * Layout (per `docs/opensquid-real-design.md` §"Phase 1 — Runtime skeleton"
+ * + §"Phases 2–7 summary" Phase 5):
+ *
+ *   ~/.opensquid/
+ *     sessions/<session-id>/
+ *       state/
+ *         <key>.json      — `write_state` / `read_state` primitives
+ *         <name>.jsonl    — `append_log` primitive
+ *     packs/<pack-id>/
+ *       state/
+ *         <key>.json      — per-pack state (Task 5.3)
+ *         <name>.jsonl    — per-pack logs (e.g. drift-catalog.jsonl)
+ *
+ * `OPENSQUID_HOME` env-var override is intentional: tests point it at
+ * `os.tmpdir()` for filesystem isolation, and self-hosting deployments
+ * may relocate state to a non-`$HOME` data directory.
+ *
+ * Always `path.join` — never raw string concat — so Windows backslashes
+ * stay sane.
+ *
+ * Imported by: src/functions/state.ts, src/runtime/drift_catalog.ts.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const OPENSQUID_HOME = () => process.env.OPENSQUID_HOME ?? join(homedir(), '.opensquid');
+// ---------------------------------------------------------------------------
+// Scope-root resolvers (G.1)
+//
+// opensquid pack discovery has two installation scopes (per G.1 spec
+// §"Pre-verified facts" pack-architecture-is-2D bullet):
+//
+//   - user scope    = `OPENSQUID_HOME()`           (`~/.opensquid/` by default)
+//   - project scope = `<project>/.opensquid/`      (walked from cwd upward)
+//
+// Each scope root may contain an `active.json` declaring which folders under
+// `packs/` are active. `discoverActivePacks(scopeRoot)` consumes the result
+// of these resolvers; null means "this scope is not in effect (no project
+// root found walking up from cwd)".
+//
+// `resolveUserScopeRoot()` is a thin alias around `OPENSQUID_HOME()` for
+// naming symmetry with the project-scope helper. The `OPENSQUID_HOME` env
+// override remains the single way tests redirect user-scope I/O — do NOT
+// duplicate the env-override logic here.
+// ---------------------------------------------------------------------------
+/**
+ * Returns the user-scope opensquid root (`~/.opensquid/` by default; honors
+ * `OPENSQUID_HOME` env override). Always returns a path; the directory may
+ * not exist yet (`discoverActivePacks` treats absent active.json as empty).
+ */
+export const resolveUserScopeRoot = () => OPENSQUID_HOME();
+/**
+ * BPDISC — Returns the built-in pack scope root: the directory whose
+ * `<root>/<name>/manifest.yaml` paths hold the packs that ship inside the
+ * opensquid npm install (`packs/builtin/`). When a user's `active.json`
+ * names a pack not found under user or project scope, the loader falls back
+ * to this root. Mirrors the OPENSQUID_HOME pattern: `OPENSQUID_BUILTIN_PACKS_ROOT`
+ * env var wins for test isolation; otherwise the path is computed relative
+ * to the dist file location at module import time.
+ *
+ * From a dist file at `<npm-root>/dist/runtime/paths.js`, the built-in
+ * packs sit at `<npm-root>/packs/builtin/` — three dirs up + `packs/builtin`.
+ * Works for both the local checkout layout (`src/runtime/paths.ts` → up to
+ * `opensquid/packs/builtin/`) and the npm-install layout (`node_modules/opensquid/dist/...`).
+ */
+export const resolveBuiltinScopeRoot = () => {
+    const envOverride = process.env.OPENSQUID_BUILTIN_PACKS_ROOT;
+    if (envOverride !== undefined && envOverride.length > 0)
+        return envOverride;
+    const here = fileURLToPath(import.meta.url);
+    // dist/runtime/paths.js → dist/runtime → dist → <npm-root> → <npm-root>/packs/builtin
+    return resolve(dirname(here), '..', '..', 'packs', 'builtin');
+};
+/**
+ * Walks up from `cwd` looking for a `.opensquid/` directory. Returns its
+ * absolute path on first hit, or `null` if the walk reaches the filesystem
+ * root without finding one (no project scope in effect).
+ *
+ * The 64-level cap protects against pathological symlink cycles. Real
+ * project trees bottom out well before 64 levels.
+ *
+ * Important: this probes for the `.opensquid/` DIRECTORY's existence, NOT
+ * the `.opensquid/project.json` FILE. The two walks have different purposes
+ * (this one answers "is there pack config here?"; `walkForProjectUuid`
+ * below answers "is there a UUID-bound project here?"). Both share the
+ * 64-level cap discipline.
+ */
+export const resolveProjectScopeRoot = async (cwd) => {
+    let dir = resolve(cwd);
+    for (let i = 0; i < 64; i++) {
+        const candidate = join(dir, '.opensquid');
+        try {
+            const st = await stat(candidate);
+            if (st.isDirectory())
+                return candidate;
+        }
+        catch {
+            /* keep walking */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+};
+/**
+ * Env-only project-UUID lookup. Returns the value of `OPENSQUID_PROJECT_UUID`
+ * if set + non-empty, else `null`. Synchronous — no I/O.
+ *
+ * Defaults to `process.env` when called without an argument; the optional
+ * `env` parameter exists for test injection.
+ */
+export function resolveProjectUuidFromEnv(env = process.env) {
+    const fromEnv = env.OPENSQUID_PROJECT_UUID;
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return fromEnv;
+    return null;
+}
+/**
+ * Walks up from `startDir` looking for `.opensquid/project.json`. Returns
+ * the parsed `uuid` on first hit (strict schema check: `version === 1 &&
+ * uuid && id`), or `null` when the walk exhausts the 64-level cap or
+ * reaches the filesystem root without a valid card.
+ *
+ * Malformed JSON, missing fields, and version mismatches all silently
+ * continue the walk — a bad ancestor card must not mask a good descendant
+ * one, and the same file might be valid under a different `version`-future
+ * revision that this consumer doesn't recognize.
+ */
+export async function walkForProjectUuid(startDir) {
+    let dir = resolve(startDir);
+    for (let i = 0; i < 64; i++) {
+        const candidate = join(dir, '.opensquid', 'project.json');
+        try {
+            const raw = await readFile(candidate, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed?.version === 1 && parsed.uuid && parsed.id)
+                return parsed.uuid;
+        }
+        catch {
+            /* keep walking */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Canonical combinator: env-first then cwd-walk. The pattern 5 call sites
+ * reimplemented before T-PUC consolidated them.
+ *
+ * Returns the first non-null source, else `null`. `env` defaults to
+ * `process.env` when omitted; `cwd` is required (callers always know which
+ * directory to walk from — there is no sensible default).
+ */
+export async function resolveProjectUuid(opts) {
+    const fromEnv = resolveProjectUuidFromEnv(opts.env);
+    if (fromEnv !== null)
+        return fromEnv;
+    return walkForProjectUuid(opts.cwd);
+}
+export const sessionStateDir = (sessionId) => join(OPENSQUID_HOME(), 'sessions', sessionId, 'state');
+export const sessionStateFile = (sessionId, key) => join(sessionStateDir(sessionId), `${key}.json`);
+export const sessionLogFile = (sessionId, name) => join(sessionStateDir(sessionId), `${name}.jsonl`);
+/**
+ * The active-task signal file (AP.2). Lives at the session ROOT, deliberately
+ * NOT under `state/`: `state/` holds pack-authored `read_state`/`write_state`
+ * keys, and the active-task signal is runtime-owned — keeping it at the root
+ * prevents a pack's `write_state` from clobbering the gate's trigger. Absent
+ * file = no active task (the "tasks-loaded" signal is off).
+ */
+export const activeTaskFile = (sessionId) => join(OPENSQUID_HOME(), 'sessions', sessionId, 'active-task.json');
+/** Archive destination for the active-task file on SessionEnd (rule #16 — archive, never silently drop). */
+export const activeTaskArchiveFile = (sessionId, stamp) => join(OPENSQUID_HOME(), 'sessions', sessionId, `active-task.${stamp}.archived.json`);
+// ---------------------------------------------------------------------------
+// Per-pack state paths (Task 5.3)
+//
+// Isolates each pack's `read_state` / `write_state` namespace under
+// `~/.opensquid/packs/<id>/state/`. Pack id is sanitized to block path
+// traversal: every non-`[a-zA-Z0-9_-]` character is replaced with `_`, so
+// `../etc/passwd` resolves to `___etc_passwd` and stays inside the pack
+// state root. The sanitization is intentionally aggressive — even `.` (no
+// hidden dirs) and `/` (no nested subpaths) collapse to `_`. Pack ids that
+// validate as plain identifiers in the manifest schema are unaffected.
+//
+// Trade-off: two distinct pack ids that differ only in non-safe characters
+// (e.g. `foo.bar` and `foo_bar`) collide on the filesystem. The validation
+// layer should reject such conflicts at load time; this helper is the
+// last-line defense against traversal, not the first.
+// ---------------------------------------------------------------------------
+const sanitizePackId = (packId) => packId.replace(/[^a-zA-Z0-9_-]/g, '_');
+export const packStateDir = (packId) => join(OPENSQUID_HOME(), 'packs', sanitizePackId(packId), 'state');
+export const packStateFile = (packId, key) => join(packStateDir(packId), `${key}.json`);
+export const packLogFile = (packId, name) => join(packStateDir(packId), `${name}.jsonl`);
+// ---------------------------------------------------------------------------
+// Daemon paths (SCHED.1)
+//
+// The unified daemon process (`OpenSquidDaemon`) owns three side-files inside
+// `OPENSQUID_HOME()`:
+//
+//   - `daemon.lock`     proper-lockfile target. We hand `realpath: false`
+//                       to the lock call so the file itself doesn't need to
+//                       exist on disk — only the `${path}.lock` directory
+//                       that proper-lockfile creates atomically via mkdir.
+//
+//   - `daemon.pid`      ASCII process id written by `start()`, removed by
+//                       `stop()`. The CLI's `daemon status` verb reads this
+//                       to report PID + uptime without needing IPC.
+//
+//   - `daemon.log`      stdout/stderr rotation target (wired by SCHED.x UI
+//                       integration; the path helper is here for symmetry).
+//
+// All three sit under `OPENSQUID_HOME()` so the `OPENSQUID_HOME` env-var
+// override extends to daemon state — tests point `OPENSQUID_HOME` at an
+// `mkdtemp` and a fresh daemon can boot in isolation without polluting the
+// developer's home directory.
+// ---------------------------------------------------------------------------
+export const daemonLockPath = () => join(OPENSQUID_HOME(), 'daemon.lock');
+export const daemonPidPath = () => join(OPENSQUID_HOME(), 'daemon.pid');
+export const daemonLogPath = () => join(OPENSQUID_HOME(), 'daemon.log');
+// ---------------------------------------------------------------------------
+// Chat-transport daemon side-files (T-CHAT-AS-TERMINAL CAT.1b).
+//
+// The rebuilt chat-transport daemon (src/channels/daemon/) owns three
+// side-files inside `OPENSQUID_HOME()`, mirroring the SCHED.1 daemon helpers
+// above but namespaced `chat-daemon.*` so the two daemons never collide on a
+// pidfile/socket:
+//
+//   - `chat-daemon.sock`  Unix-socket the outbound `send` JSON-RPC listens on.
+//                         Consumed live by src/mcp/chat-bridge-server.ts +
+//                         src/runtime/agent_bridge/tools/chat_send.ts — the
+//                         path must stay byte-identical to those callers'
+//                         `join(root, 'chat-daemon.sock')`. Windows uses a
+//                         named pipe instead (no filesystem residue); the
+//                         protocol module derives it.
+//   - `chat-daemon.pid`   worker pid, written on boot + removed on clean exit.
+//   - `chat-daemon.log`   detached-spawn stdout/stderr target.
+//
+// All three honor the `OPENSQUID_HOME` override so tests boot a daemon in an
+// `mkdtemp` without touching the developer's home dir.
+// ---------------------------------------------------------------------------
+export const chatDaemonSockPath = () => join(OPENSQUID_HOME(), 'chat-daemon.sock');
+export const chatDaemonPidPath = () => join(OPENSQUID_HOME(), 'chat-daemon.pid');
+export const chatDaemonLogPath = () => join(OPENSQUID_HOME(), 'chat-daemon.log');
+// ---------------------------------------------------------------------------
+// Per-project chat inbox. The chat-daemon appends one inbound message per line
+// to `<home>/projects/<uuid>/inbox/<platform>.jsonl` (the on-disk contract the
+// agent_bridge + `chat watch` both consume). Honors OPENSQUID_HOME so tests
+// and self-hosting relocate it with the rest of the layout.
+// ---------------------------------------------------------------------------
+export const inboxFile = (projectUuid, platform) => join(OPENSQUID_HOME(), 'projects', projectUuid, 'inbox', `${platform}.jsonl`);
+// LL.1 (2026-05-30) — sibling helpers for the inbox directory + ack ledger.
+// `inboxDir` is the parent of the per-platform JSONL files; `inboxAckedPath`
+// is the per-project append-only ack ledger consumed by LL.4's UPS hook.
+export const inboxDir = (projectUuid) => join(OPENSQUID_HOME(), 'projects', projectUuid, 'inbox');
+export const inboxAckedPath = (projectUuid) => join(OPENSQUID_HOME(), 'projects', projectUuid, 'inbox', 'acked.jsonl');
+// Live-session lease: while `chat watch` runs for a project, it heartbeats this
+// file so the always-on agent-bridge daemon can tell a live interactive session
+// is handling the project and stay silent (cross-session arbitration, T-DEL).
+export const liveSessionLease = (projectUuid) => join(OPENSQUID_HOME(), 'projects', projectUuid, 'live-session.lease');
+// T-RJ-FOLLOWUPS FU.3 (2026-06-01) — project-scoped live-session pointer. The
+// UPS hook writes the real session id here (keyed by project), and the MCP
+// server reads it via `CLAUDE_PROJECT_DIR`→`resolveProjectUuid`. Race-free
+// across projects: a concurrent session in ANOTHER repo writes a DIFFERENT
+// project's pointer and can't clobber this one (the global `.current-session`
+// is last-writer-wins across all sessions; this is not).
+export const projectCurrentSessionPath = (projectUuid) => join(OPENSQUID_HOME(), 'projects', projectUuid, '.current-session');
+// ---------------------------------------------------------------------------
+// Umbrella chat inbox (T-CHAT-AS-TERMINAL CAT.1b/1c). The rebuilt chat-daemon
+// keys the inbox + lease by UMBRELLA id (`loop`, `raumpilates-fe`, the reserved
+// `general`) instead of per-cwd project_uuid — one umbrella ↔ one chat session
+// (invariants #2/#4), which also retires the da96≡0742 mirror. Same on-disk row
+// + lease shapes as the project-keyed helpers above; only the key changes.
+// Orphan (unrouted-at-transport) messages keep the legacy top-level location.
+// ---------------------------------------------------------------------------
+export const umbrellaInboxFile = (umbrellaId, platform) => join(OPENSQUID_HOME(), 'umbrellas', umbrellaId, 'inbox', `${platform}.jsonl`);
+export const umbrellaInboxDir = (umbrellaId) => join(OPENSQUID_HOME(), 'umbrellas', umbrellaId, 'inbox');
+export const umbrellaInboxAckedPath = (umbrellaId) => join(OPENSQUID_HOME(), 'umbrellas', umbrellaId, 'inbox', 'acked.jsonl');
+export const umbrellaLiveSessionLease = (umbrellaId) => join(OPENSQUID_HOME(), 'umbrellas', umbrellaId, 'live-session.lease');
+export const umbrellaCurrentSessionPath = (umbrellaId) => join(OPENSQUID_HOME(), 'umbrellas', umbrellaId, '.current-session');
+// CAT.3 — chat-driven-turn marker. Written (with the driving session id) when the
+// Stop hook DRIVES a turn from an inbound chat message (CAT.2); consumed (the
+// just-completed turn's output streams to the source topic, then the marker is
+// deleted) by the NEXT Stop. So a chat-IN turn streams its output OUT to chat,
+// while a terminal-driven turn does not (no flood).
+export const umbrellaChatDrivenMarker = (umbrellaId) => join(OPENSQUID_HOME(), 'umbrellas', umbrellaId, '.chat-driven');
+// CAT.4 — inbound media download dir. The telegram adapter downloads photos +
+// documents here before emitting an `InboundMedia` pointer; the inbox drain
+// injects `📎 <kind>: <path>` and the agent Reads the path to view the file.
+// Honors OPENSQUID_HOME so tests relocate downloads into an mkdtemp.
+export const inboundMediaDir = () => join(OPENSQUID_HOME(), 'media', 'inbound');
+// Transport-level orphan inbox: a message that resolves to no umbrella
+// (`resolveInboundUmbrella` → null). Kept at the legacy top-level path so the
+// existing orphan-audit tooling keeps working.
+export const orphanInboxFile = (platform) => join(OPENSQUID_HOME(), 'inbox', 'orphan', `${platform}.jsonl`);
+//# sourceMappingURL=paths.js.map

package/dist/runtime/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/runtime/paths.ts"],"names":[],"mappings":"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"}

package/dist/runtime/phase_ledger.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Durable per-task phase ledger — the TS owner of the filesystem YAML ledger
+ * the Rust engine used to write via `task.log_phase` (retire-Rust slice).
+ *
+ * Layout (UNCHANGED from the engine, so existing on-disk ledgers stay valid):
+ *
+ *   <OPENSQUID_HOME ?? ~/.opensquid>/phase_ledger/<taskId>/<phase>.yaml
+ *
+ * ONE FILE PER PHASE; each holds `phase` / `logged_at` (ISO) / optional `note`.
+ * Re-logging a phase overwrites its file (idempotent — the engine's per-phase
+ * shape, not an append log).
+ *
+ * Why filesystem YAML and not libSQL: locked design decision (2026-05-17) —
+ * the phase ledger is "small, write-mostly, fine as YAML" and explicitly stays
+ * filesystem-based, NOT in the libsql DB. This slice moves the WRITER off Rust,
+ * it does NOT change the storage medium.
+ *
+ * This is the DURABLE audit ledger. It is SEPARATE from the gate-readable
+ * session-state ledger (`runtime/workflow_phases.ts`), which `handleLogPhase`
+ * also writes and which the commit gate reads — that one is untouched here.
+ *
+ * Imports from: node:fs/promises, node:os, node:path, yaml, ./atomic_write.js.
+ * Imported by: src/mcp/tools/log_phase.ts (+ its read-back test).
+ */
+export interface PhaseLedgerEntry {
+    phase: string;
+    logged_at: string;
+    note?: string;
+}
+/** The read-back shape — mirrors the engine's `TaskGetLedgerResult` so the
+ *  read-back test (and any future reader) ports 1:1. */
+export interface PhaseLedger {
+    task_id: string;
+    phases_logged: string[];
+    entries: PhaseLedgerEntry[];
+}
+/**
+ * `<OPENSQUID_HOME ?? ~/.opensquid>/phase_ledger/<taskId>`. OPENSQUID_HOME-aware
+ * so tests isolate to a tmp home and the real ledger dir resolves in production
+ * (same rooting pattern as `session_state` + `store_lesson`).
+ */
+export declare function phaseLedgerDir(taskId: string): string;
+/**
+ * Write `<phase>.yaml` for a task. `mkdir -p` the task dir, then atomic
+ * (tmp+rename) write so a crash can't leave a truncated file. The `nowIso`
+ * seam keeps `logged_at` deterministic in tests.
+ */
+export declare function writePhaseLedger(taskId: string, phase: string, note?: string, nowIso?: () => string): Promise<void>;
+/**
+ * Read every `<phase>.yaml` for a task into the `TaskGetLedgerResult` shape.
+ * Absent dir → empty ledger (no throw). A malformed `<phase>.yaml` is skipped,
+ * not fatal — one bad file must not blind the whole ledger (same no-throw-read
+ * discipline as the session-state + active-task helpers).
+ */
+export declare function readPhaseLedger(taskId: string): Promise<PhaseLedger>;
+//# sourceMappingURL=phase_ledger.d.ts.map

package/dist/runtime/phase_ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase_ledger.d.ts","sourceRoot":"","sources":["../../src/runtime/phase_ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;wDACwD;AACxD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EACb,MAAM,GAAE,MAAM,MAAuC,GACpD,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0B1E"}

package/dist/runtime/phase_ledger.js

@@ -0,0 +1,88 @@
+/**
+ * Durable per-task phase ledger — the TS owner of the filesystem YAML ledger
+ * the Rust engine used to write via `task.log_phase` (retire-Rust slice).
+ *
+ * Layout (UNCHANGED from the engine, so existing on-disk ledgers stay valid):
+ *
+ *   <OPENSQUID_HOME ?? ~/.opensquid>/phase_ledger/<taskId>/<phase>.yaml
+ *
+ * ONE FILE PER PHASE; each holds `phase` / `logged_at` (ISO) / optional `note`.
+ * Re-logging a phase overwrites its file (idempotent — the engine's per-phase
+ * shape, not an append log).
+ *
+ * Why filesystem YAML and not libSQL: locked design decision (2026-05-17) —
+ * the phase ledger is "small, write-mostly, fine as YAML" and explicitly stays
+ * filesystem-based, NOT in the libsql DB. This slice moves the WRITER off Rust,
+ * it does NOT change the storage medium.
+ *
+ * This is the DURABLE audit ledger. It is SEPARATE from the gate-readable
+ * session-state ledger (`runtime/workflow_phases.ts`), which `handleLogPhase`
+ * also writes and which the commit gate reads — that one is untouched here.
+ *
+ * Imports from: node:fs/promises, node:os, node:path, yaml, ./atomic_write.js.
+ * Imported by: src/mcp/tools/log_phase.ts (+ its read-back test).
+ */
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
+import { atomicWriteFile } from './atomic_write.js';
+/**
+ * `<OPENSQUID_HOME ?? ~/.opensquid>/phase_ledger/<taskId>`. OPENSQUID_HOME-aware
+ * so tests isolate to a tmp home and the real ledger dir resolves in production
+ * (same rooting pattern as `session_state` + `store_lesson`).
+ */
+export function phaseLedgerDir(taskId) {
+    const root = process.env.OPENSQUID_HOME ?? join(homedir(), '.opensquid');
+    return join(root, 'phase_ledger', taskId);
+}
+/**
+ * Write `<phase>.yaml` for a task. `mkdir -p` the task dir, then atomic
+ * (tmp+rename) write so a crash can't leave a truncated file. The `nowIso`
+ * seam keeps `logged_at` deterministic in tests.
+ */
+export async function writePhaseLedger(taskId, phase, note, nowIso = () => new Date().toISOString()) {
+    const dir = phaseLedgerDir(taskId);
+    await mkdir(dir, { recursive: true });
+    const entry = {
+        phase,
+        logged_at: nowIso(),
+        ...(note !== undefined ? { note } : {}),
+    };
+    await atomicWriteFile(join(dir, `${phase}.yaml`), yamlStringify(entry));
+}
+/**
+ * Read every `<phase>.yaml` for a task into the `TaskGetLedgerResult` shape.
+ * Absent dir → empty ledger (no throw). A malformed `<phase>.yaml` is skipped,
+ * not fatal — one bad file must not blind the whole ledger (same no-throw-read
+ * discipline as the session-state + active-task helpers).
+ */
+export async function readPhaseLedger(taskId) {
+    const dir = phaseLedgerDir(taskId);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { task_id: taskId, phases_logged: [], entries: [] };
+    }
+    const entries = [];
+    for (const name of names) {
+        if (!name.endsWith('.yaml'))
+            continue;
+        try {
+            const parsed = yamlParse(await readFile(join(dir, name), 'utf8'));
+            if (parsed !== null &&
+                typeof parsed === 'object' &&
+                typeof parsed.phase === 'string' &&
+                typeof parsed.logged_at === 'string') {
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // skip a malformed / unreadable file
+        }
+    }
+    return { task_id: taskId, phases_logged: entries.map((e) => e.phase), entries };
+}
+//# sourceMappingURL=phase_ledger.js.map

package/dist/runtime/phase_ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase_ledger.js","sourceRoot":"","sources":["../../src/runtime/phase_ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAEtE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAgBpD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAc,EACd,KAAa,EACb,IAAa,EACb,SAAuB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAErD,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,KAAK,GAAqB;QAC9B,KAAK;QACL,SAAS,EAAE,MAAM,EAAE;QACnB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC;IACF,MAAM,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc;IAClD,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC7D,CAAC;IACD,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAY,CAAC;YAC7E,IACE,MAAM,KAAK,IAAI;gBACf,OAAO,MAAM,KAAK,QAAQ;gBAC1B,OAAQ,MAA2B,CAAC,KAAK,KAAK,QAAQ;gBACtD,OAAQ,MAA2B,CAAC,SAAS,KAAK,QAAQ,EAC1D,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,MAA0B,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,qCAAqC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;AAClF,CAAC"}

package/dist/runtime/pinned_skills.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pinned-skill semantics for universal-scope packs (Phase 3 Task 3.5).
+ *
+ * Purpose: partition every skill across the loaded pack set into two
+ * disjoint groups — `pinned` (always-on for this user) and `dynamic`
+ * (subject to when_to_load + unloads_when evaluation). The dispatcher
+ * loads pinned skills at session start and keeps them resident until
+ * session end; dynamic skills flow through the prefilter + router +
+ * unload tick pipeline.
+ *
+ * The rule (per design doc §"Phases 2–7 summary" Phase 3):
+ *
+ *     Universal-scope pack + load: preload skill  →  PINNED
+ *     Everything else                              →  DYNAMIC
+ *
+ * Pinned semantics encode "this is foundational hygiene for THIS user"
+ * (see `project_opensquid_personal_rules_are_user_pack` — Sangmin's
+ * 17 anti-drift rules are exactly this kind of pack). Universal scope
+ * is the user-pack tier; preload says "load immediately, do not wait
+ * for a matcher". The intersection is the pin.
+ *
+ * Workflow / domain / specialty / project packs CANNOT pin even if
+ * they're authored with `load: preload` — preload at those scopes
+ * means "load when the scope activates" (the dispatcher decides when),
+ * not "load forever". A workflow's preload skills are still dynamic
+ * from the partition's point of view; they just have an empty
+ * `when_to_load` and so activate at workflow-activation time.
+ *
+ * Contradiction detection: a universal-scope pack that declares
+ * `unloads_when` on a skill that ALSO has `load: preload` is
+ * pathological — the partition pins the skill (preload + universal
+ * wins), but the pack author also asked it to unload. We emit a
+ * stderr warning so the user sees the inconsistency. The pin takes
+ * precedence; the dispatcher (Phase 4 wiring) MUST skip the unload
+ * evaluator for pinned skills.
+ *
+ * The function is pure (no I/O beyond stderr warnings) so it's safe
+ * to call from any layer that has the resolved pack set.
+ *
+ * Imports from: ./types.js (Pack + Skill types).
+ * Imported by: src/runtime/index.ts (re-exported as `partitionSkills`
+ *   + `SkillSet`) and the dispatcher's session-bootstrap path once
+ *   Phase 3 wiring lands.
+ */
+import type { Pack, Skill } from './types.js';
+export interface SkillSet {
+    pinned: {
+        pack: Pack;
+        skill: Skill;
+    }[];
+    dynamic: {
+        pack: Pack;
+        skill: Skill;
+    }[];
+}
+/**
+ * Partition every skill across `packs` into pinned (universal+preload) and
+ * dynamic (everything else). Pure function — the only side effect is a
+ * stderr warning when a universal-pack skill has BOTH `load: preload` and
+ * a non-empty `unloads_when` (contradictory).
+ */
+export declare function partitionSkills(packs: Pack[]): SkillSet;
+//# sourceMappingURL=pinned_skills.d.ts.map

package/dist/runtime/pinned_skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned_skills.d.ts","sourceRoot":"","sources":["../../src/runtime/pinned_skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAY9C,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;IACvC,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,CA2BvD"}

package/dist/runtime/pinned_skills.js

@@ -0,0 +1,75 @@
+/**
+ * Pinned-skill semantics for universal-scope packs (Phase 3 Task 3.5).
+ *
+ * Purpose: partition every skill across the loaded pack set into two
+ * disjoint groups — `pinned` (always-on for this user) and `dynamic`
+ * (subject to when_to_load + unloads_when evaluation). The dispatcher
+ * loads pinned skills at session start and keeps them resident until
+ * session end; dynamic skills flow through the prefilter + router +
+ * unload tick pipeline.
+ *
+ * The rule (per design doc §"Phases 2–7 summary" Phase 3):
+ *
+ *     Universal-scope pack + load: preload skill  →  PINNED
+ *     Everything else                              →  DYNAMIC
+ *
+ * Pinned semantics encode "this is foundational hygiene for THIS user"
+ * (see `project_opensquid_personal_rules_are_user_pack` — Sangmin's
+ * 17 anti-drift rules are exactly this kind of pack). Universal scope
+ * is the user-pack tier; preload says "load immediately, do not wait
+ * for a matcher". The intersection is the pin.
+ *
+ * Workflow / domain / specialty / project packs CANNOT pin even if
+ * they're authored with `load: preload` — preload at those scopes
+ * means "load when the scope activates" (the dispatcher decides when),
+ * not "load forever". A workflow's preload skills are still dynamic
+ * from the partition's point of view; they just have an empty
+ * `when_to_load` and so activate at workflow-activation time.
+ *
+ * Contradiction detection: a universal-scope pack that declares
+ * `unloads_when` on a skill that ALSO has `load: preload` is
+ * pathological — the partition pins the skill (preload + universal
+ * wins), but the pack author also asked it to unload. We emit a
+ * stderr warning so the user sees the inconsistency. The pin takes
+ * precedence; the dispatcher (Phase 4 wiring) MUST skip the unload
+ * evaluator for pinned skills.
+ *
+ * The function is pure (no I/O beyond stderr warnings) so it's safe
+ * to call from any layer that has the resolved pack set.
+ *
+ * Imports from: ./types.js (Pack + Skill types).
+ * Imported by: src/runtime/index.ts (re-exported as `partitionSkills`
+ *   + `SkillSet`) and the dispatcher's session-bootstrap path once
+ *   Phase 3 wiring lands.
+ */
+/**
+ * Partition every skill across `packs` into pinned (universal+preload) and
+ * dynamic (everything else). Pure function — the only side effect is a
+ * stderr warning when a universal-pack skill has BOTH `load: preload` and
+ * a non-empty `unloads_when` (contradictory).
+ */
+export function partitionSkills(packs) {
+    const pinned = [];
+    const dynamic = [];
+    for (const pack of packs) {
+        for (const skill of pack.skills) {
+            const isPinned = pack.scope === 'universal' && skill.load === 'preload';
+            if (isPinned) {
+                if (skill.unloads_when.length > 0) {
+                    // Author asked for both pin and unload — keep the pin, warn loudly.
+                    // stderr (not stdout) so this doesn't pollute MCP stdout JSON-RPC
+                    // when the runtime is hosted under a stdio MCP server.
+                    process.stderr.write(`[opensquid] warning: universal-scope pack "${pack.name}" declares ` +
+                        `unloads_when on pinned skill "${skill.name}" — unloads_when will ` +
+                        `be ignored (pinned skills are resident for the whole session).\n`);
+                }
+                pinned.push({ pack, skill });
+            }
+            else {
+                dynamic.push({ pack, skill });
+            }
+        }
+    }
+    return { pinned, dynamic };
+}
+//# sourceMappingURL=pinned_skills.js.map

package/dist/runtime/pinned_skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned_skills.js","sourceRoot":"","sources":["../../src/runtime/pinned_skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAmBH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,MAAM,OAAO,GAAwB,EAAE,CAAC;IAExC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;YAExE,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAClC,oEAAoE;oBACpE,kEAAkE;oBAClE,uDAAuD;oBACvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8CAA8C,IAAI,CAAC,IAAI,aAAa;wBAClE,iCAAiC,KAAK,CAAC,IAAI,wBAAwB;wBACnE,kEAAkE,CACrE,CAAC;gBACJ,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}