kankaku 0.5.0 → 0.6.0

package/dist/config.js

@@ -0,0 +1,392 @@
+import { BUILTIN_SUBAGENT_PROFILES, buildConfiguredProfile, matchesAnyMarker } from "./domain/subagent-profile.js";
+const DEFAULT_DIR = ".kankaku";
+const DEFAULT_INTERACTIVE_TOOLS = ["ask_user_question", "ask_user_choice"];
+/**
+ * Default segment rule: with gentle-ai, the review-with-receipts step runs
+ * as `gentle-ai review ...` commands through the `bash` tool, so tag that
+ * span `review`.
+ */
+const DEFAULT_SEGMENT_RULES = [{ tag: "review", tool: "bash", pattern: /\bgentle-ai review\b/ }];
+/** Tags allowed for a segment rule: letters, digits, `_` and `-`, 1-32 chars. */
+const SAFE_TAG = /^[A-Za-z0-9_-]{1,32}$/;
+/** Property names that behave specially on a plain object; never usable as a tag. */
+const RESERVED_TAGS = new Set(["__proto__", "constructor", "prototype"]);
+function isSafeTag(tag) {
+    return SAFE_TAG.test(tag) && !RESERVED_TAGS.has(tag);
+}
+/**
+ * Parse `KANKAKU_SEGMENTS`, a `;`-separated list of `tag=tool:regex`
+ * entries (example: `review=bash:gentle-ai review;commit=bash:git commit`).
+ * Malformed entries (missing tag, tool or regex, an invalid regex source,
+ * or a tag that is not a safe identifier such as `__proto__`) are skipped
+ * rather than failing the whole variable.
+ */
+function parseSegmentRules(raw) {
+    const rules = [];
+    for (const entry of raw.split(";")) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex <= 0)
+            continue;
+        const tag = trimmed.slice(0, eqIndex).trim();
+        const rest = trimmed.slice(eqIndex + 1);
+        const colonIndex = rest.indexOf(":");
+        if (colonIndex <= 0)
+            continue;
+        const tool = rest.slice(0, colonIndex).trim();
+        const regexSource = rest.slice(colonIndex + 1).trim();
+        if (!tag || !tool || !regexSource || !isSafeTag(tag))
+            continue;
+        try {
+            rules.push({ tag, tool, pattern: new RegExp(regexSource) });
+        }
+        catch {
+            continue;
+        }
+    }
+    return rules;
+}
+/**
+ * SUBAGENT-REQ-002: `KANKAKU_SUBAGENT_TOOLS`, a comma-separated list of
+ * additional tool names treated as subagent-launching spans, parsed with
+ * the exact same tolerant trim-and-filter-empty convention as
+ * `KANKAKU_INTERACTIVE_TOOLS` above.
+ */
+function parseSubagentTools(raw) {
+    return raw
+        .split(",")
+        .map((tool) => tool.trim())
+        .filter((tool) => tool.length > 0);
+}
+/**
+ * SUBAGENT-REQ-003: `KANKAKU_SUBAGENT_CHILD_ENV`, a `;`-separated list of
+ * `NAME=VALUE` or bare `NAME` child-process env markers — mirrors
+ * `KANKAKU_SEGMENTS`'s tolerant `;`-separated convention. A bare `NAME`
+ * marks presence-only (any non-empty value matches, e.g. pi-subagents'
+ * depth counter); `NAME=VALUE` requires an exact match. An entry with no
+ * name, or a trailing `=` with nothing after it, is malformed and skipped
+ * rather than failing the whole variable.
+ */
+function parseSubagentChildEnv(raw) {
+    const markers = [];
+    for (const entry of raw.split(";")) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1) {
+            const name = trimmed;
+            if (name)
+                markers.push({ name });
+            continue;
+        }
+        const name = trimmed.slice(0, eqIndex).trim();
+        const value = trimmed.slice(eqIndex + 1).trim();
+        if (!name || !value)
+            continue;
+        markers.push({ name, value });
+    }
+    return markers;
+}
+/**
+ * C2 (CRITICAL fix, item 1): exact marker names pi sets on EVERY process it
+ * runs (verified: `dist/cli/setup.js:5` sets `PI_CODING_AGENT=true`,
+ * `dist/rpc-entry.js:6` sets `AI_AGENT=pi` — both unconditionally, not just
+ * for a subagent's child) or that are otherwise ordinary, ambient
+ * shell/OS/npm-lifecycle environment, never something a real child-only
+ * marker would legitimately reuse.
+ */
+const DENIED_MARKER_NAMES = new Set(["PI_CODING_AGENT", "AI_AGENT", "PATH", "HOME", "USER", "SHELL", "PWD", "CI", "LANG", "TMUX"]);
+/** C2 item 1: namespace prefixes an ambient variable is overwhelmingly likely to fall under — a genuine child-only marker should never need one of these either. */
+const DENIED_MARKER_PREFIXES = ["PI_", "TERM", "LC_", "NODE_", "NPM_", "KANKAKU_"];
+/** What an environment variable name may look like; anything else is a typo, never a marker. */
+const VALID_MARKER_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** `undefined` when `name` is an acceptable marker name; otherwise a human-readable reason it was rejected. Matching is case-insensitive — an env var name's case carries no meaning here. */
+function deniedMarkerReason(name) {
+    // A name that is not a valid environment variable name can never match a
+    // real variable: accepting it would silently disable the user's
+    // configuration AND hide any ambient name inside it from the denylist
+    // below. The usual cause is typing commas, as `KANKAKU_SUBAGENT_TOOLS`
+    // takes, where this list is `;`-separated.
+    if (!VALID_MARKER_NAME.test(name)) {
+        return `"${name}" is not a valid environment variable name — separate several markers with ";" (not ","), each as NAME or NAME=VALUE`;
+    }
+    const upper = name.toUpperCase();
+    if (DENIED_MARKER_NAMES.has(upper)) {
+        return `${name} is an ambient variable pi or the shell sets on EVERY process, not a marker exclusive to a subagent's child`;
+    }
+    for (const prefix of DENIED_MARKER_PREFIXES) {
+        if (upper.startsWith(prefix)) {
+            return `${name} looks like a pi/npm/shell-namespaced environment variable (prefix "${prefix}"), not a marker a third-party subagent tool would set`;
+        }
+    }
+    return undefined;
+}
+/**
+ * C2 (CRITICAL fix, item 1): validate every `KANKAKU_SUBAGENT_CHILD_ENV`
+ * marker against the denylist above, config-time. A rejected marker is
+ * never added to the `"configured"` profile — so it can never demote a
+ * user's own top-level session to `role: "subagent"` in the first place
+ * (layered with C2 items 2/3's runtime interactive guard in
+ * `config.ts#detectRole`, which still protects a marker this denylist does
+ * not happen to catch). `loadConfig` surfaces `rejected` via
+ * `KankakuConfig.rejectedSubagentChildEnvMarkers` for `/kankaku doctor` and
+ * a one-time `ctx.ui.notify`.
+ */
+export function validateSubagentChildEnvMarkers(markers) {
+    const accepted = [];
+    const rejected = [];
+    for (const marker of markers) {
+        const reason = deniedMarkerReason(marker.name);
+        if (reason) {
+            rejected.push({ name: marker.name, reason });
+        }
+        else {
+            accepted.push(marker);
+        }
+    }
+    return { accepted, rejected };
+}
+export function loadConfig(env = process.env) {
+    const dir = env["KANKAKU_DIR"]?.trim() || DEFAULT_DIR;
+    const interactiveToolsRaw = env["KANKAKU_INTERACTIVE_TOOLS"]?.trim();
+    const interactiveTools = interactiveToolsRaw
+        ? interactiveToolsRaw
+            .split(",")
+            .map((tool) => tool.trim())
+            .filter((tool) => tool.length > 0)
+        : DEFAULT_INTERACTIVE_TOOLS;
+    const segmentsRaw = env["KANKAKU_SEGMENTS"]?.trim();
+    const segmentRules = segmentsRaw ? parseSegmentRules(segmentsRaw) : DEFAULT_SEGMENT_RULES;
+    const client = env["KANKAKU_CLIENT"]?.trim() || undefined;
+    const subagentToolsRaw = env["KANKAKU_SUBAGENT_TOOLS"]?.trim();
+    const configuredTools = subagentToolsRaw ? parseSubagentTools(subagentToolsRaw) : [];
+    const subagentChildEnvRaw = env["KANKAKU_SUBAGENT_CHILD_ENV"]?.trim();
+    const parsedMarkers = subagentChildEnvRaw ? parseSubagentChildEnv(subagentChildEnvRaw) : [];
+    // C2 (CRITICAL fix, item 1): a denylisted marker name is never handed to
+    // buildConfiguredProfile at all — it can never demote a session's role,
+    // and is instead surfaced via rejectedSubagentChildEnvMarkers below.
+    const { accepted: configuredMarkers, rejected: rejectedSubagentChildEnvMarkers } = validateSubagentChildEnvMarkers(parsedMarkers);
+    const configuredProfile = buildConfiguredProfile(configuredTools, configuredMarkers);
+    const subagentProfiles = [...BUILTIN_SUBAGENT_PROFILES, ...(configuredProfile ? [configuredProfile] : [])];
+    return {
+        dir,
+        interactiveTools,
+        subagentProfiles,
+        segmentRules,
+        rejectedSubagentChildEnvMarkers,
+        ...(client !== undefined ? { client } : {}),
+    };
+}
+/**
+ * `KANKAKU_ROLE`: an explicit escape hatch for a genuine session
+ * `detectRole` gets wrong (no reliable automatic signal exists for it),
+ * and for a legacy/JSONL record already written `uncertain`, which can
+ * never be rewritten after the fact (the log is append-only) but whose
+ * *next* run can be told the truth directly. It does **not** override
+ * every other signal unconditionally any more — see `detectRole`'s
+ * precedence doc (R1) for the confirmed-child-marker and interactive-
+ * session exceptions this now has. An unrecognised value (anything other
+ * than exactly `"orchestrator"` or `"subagent"`) is ignored, falling back
+ * to normal detection, rather than failing the process or guessing.
+ */
+export function readRoleOverride(env = process.env) {
+    const raw = env["KANKAKU_ROLE"]?.trim();
+    return raw === "orchestrator" || raw === "subagent" ? raw : undefined;
+}
+/**
+ * Remove `KANKAKU_ROLE` from `env` in place (R1, layer 2 — non-
+ * propagation). `KANKAKU_ROLE` decides only THIS process's role; a child
+ * this process spawns (a subagent runner, a tool shell) must never inherit
+ * it, since `process.env` is inherited by every OS child by default. Left
+ * unstripped, a user who once hit a false `uncertain` and exported
+ * `KANKAKU_ROLE=orchestrator` in a shell rc/tmux/CI environment would have
+ * every subsequent subagent see it too — layer 1's precedence fix
+ * (a confirmed child marker always wins) already neutralises that specific
+ * leak for a *recognised* subagent mechanism, but this strips it outright
+ * so it can never reach an unrecognised one, or reach an unrelated child
+ * process this one spawns for some other reason. Takes the env object as
+ * a parameter, rather than reaching for `process.env` itself, so this
+ * stays a pure function tests can exercise against a plain object without
+ * ever mutating the real environment — `extension.ts` is the one caller
+ * that passes the real `process.env`, right after reading the override.
+ */
+export function stripRoleOverride(env) {
+    delete env["KANKAKU_ROLE"];
+}
+/**
+ * Classify this process's role, strictly in this order (R1 rewrote this
+ * precedence — a leaked `KANKAKU_ROLE` must never out-rank a *confirmed*
+ * signal, and must never silently drop a genuine interactive session):
+ *
+ * 1. `GENTLE_PI_AGENTS_CHILD=1` — the automatic confirmed-subagent marker,
+ *    set only by the subagent runner itself, never something a shell
+ *    rc/tmux/CI environment would export. **Always wins**, even over an
+ *    explicit `KANKAKU_ROLE=orchestrator` — without this, a leaked
+ *    `KANKAKU_ROLE=orchestrator` export would turn every one of this
+ *    process's genuine subagent invocations into a confirmed,
+ *    independently-billed orchestrator too (the bug this fixes).
+ * 2. `KANKAKU_ROLE` (F3's explicit escape hatch), when set to a recognised
+ *    value and no confirmed marker matched above — with one exception:
+ *    `KANKAKU_ROLE=subagent` in an **interactive** session (`isInteractive`
+ *    — see below) is ignored. No subagent mechanism kankaku recognises
+ *    ever launches its child interactively; an interactive session with
+ *    this override set and no marker to back it up is therefore almost
+ *    certainly a leaked shell export, not a real subagent. Honouring it
+ *    would silently drop this session's own work from every report and
+ *    the hub (an orphaned subagent record that never anchors a task) with
+ *    no way to recover it later, since `worklog.jsonl` is append-only.
+ *    Between the package's two guiding rules — "undercount is recoverable,
+ *    overcount is not" (which governs the *opposite* risk, inventing extra
+ *    billing, and does not apply here) and "never silently drop genuine
+ *    work" — this is governed by the second: the override is ignored, this
+ *    process is classified `orchestrator` (what it structurally must be),
+ *    and `overrideIgnoredInteractive` is set so the caller can surface the
+ *    contradiction instead of resolving it silently. A non-interactive
+ *    process gets exactly what it asked for. `KANKAKU_ROLE=orchestrator`
+ *    has no such exception — forcing a session `orchestrator` can never
+ *    drop work, only (rarely) invent a task that should not exist, a risk
+ *    the user accepted by setting it explicitly.
+ * 3. `hasTrackedAncestor` — whether this process's own OS ancestor chain
+ *    contains a live, identity-verified entry in the machine-wide process
+ *    registry (computed by the caller, e.g. `adapters/subagent-startup.ts`,
+ *    via `adapters/ancestry.ts` + `domain/ancestry-match.ts`; see
+ *    `ports/process-registry.ts`) — combined with `isInteractive`: only a
+ *    *non-interactive* process with a tracked ancestor is demoted to
+ *    `uncertain` (ADR 0022's safe default, inverted). An interactive TUI
+ *    session on a real terminal is a human's own session even when some
+ *    ancestor happens to be a tracked pi process (e.g. pi launched from
+ *    inside another pi's shell tool) — every subagent mechanism kankaku
+ *    recognises launches its child non-interactively over pipes, so
+ *    `isInteractive` alone already tells a genuine top-level session apart
+ *    from one that could plausibly be someone's silent child.
+ *
+ * `isInteractive` defaults to `true` — the same conservative default used
+ * for both the interactive-override exception above and the `uncertain`
+ * fallback below, since a caller that does not yet know it (see
+ * `extension.ts`'s factory-time synchronous TTY proxy, and F3's later,
+ * authoritative `ctx.mode === "tui"` refinement of `roleConfidence` only —
+ * never of `role` itself) should never wrongly honour a `subagent` override
+ * or demote a session to `uncertain` before it can find out.
+ *
+ * A process that cannot be shown to be top-level by any of the above must
+ * never default to `"orchestrator"` outright — but see F2: when ancestor
+ * detection itself is unavailable (platform, or a failed/timed-out probe),
+ * `hasTrackedAncestor` is simply `false` (nothing was found), which already
+ * falls through to a confirmed orchestrator here — the *old*, pre-ADR-0022
+ * behaviour on such a platform, deliberately: marking every unprovable
+ * process `uncertain` there would drop all of a Windows user's genuine
+ * work, a far worse failure than the narrow overcount this guards against
+ * elsewhere. `/kankaku doctor` is responsible for making that unavailable-
+ * detection limitation visible; it is never encoded in `roleConfidence`.
+ *
+ * C2 (CRITICAL fix): `childMarkers` (built-in tier, step 1 above) and
+ * `configuredMarkers` (the 5th param) are now two DIFFERENT tiers, not one
+ * merged list. A BUILT-IN marker (`GENTLE_PI_AGENTS_CHILD`,
+ * `PI_SUBAGENT_DEPTH`) is set only by a real subagent runner and always
+ * wins outright, exactly as step 1 describes — verified that no built-in
+ * mechanism kankaku recognises ever launches its child interactively (see
+ * `domain/subagent-profile.ts#PI_SUBAGENTS_PROFILE`'s doc comment), so this
+ * tier never actually needs the interactive exception in practice, and
+ * keeping it unconditional avoids a behaviour change for it. A
+ * USER-CONFIGURED marker (`KANKAKU_SUBAGENT_CHILD_ENV`), by contrast, names
+ * an arbitrary environment variable kankaku cannot verify is child-only —
+ * pi itself sets `PI_CODING_AGENT`/`AI_AGENT` on EVERY process, and a naive
+ * choice like that (or `CI`, `TMUX`, an exported shell var) would make the
+ * user's own top-level interactive session `role: "subagent"` with no
+ * parent, never anchoring a task and unrecoverable once written (the log
+ * is append-only). So a configured marker gets EXACTLY the same
+ * interactive exception `KANKAKU_ROLE=subagent` already has (step 2): it
+ * never demotes an interactive session — `configuredMarkerIgnoredInteractive`
+ * is set instead, so the caller can self-check and surface the
+ * contradiction (C2 item 3) rather than silently trusting an ambient
+ * marker. See `config.ts#loadConfig`'s denylist for the config-time half of
+ * this fix (rejecting an obviously-ambient marker name outright).
+ */
+/** `detectRole`'s default `childMarkers` when a caller does not pass its own active profile set — identical to the single marker this function hardcoded before SUBAGENT-REQ-001/002/003, so every pre-existing 3-arg call site keeps behaving exactly as before. */
+const DEFAULT_CHILD_MARKERS = [{ name: "GENTLE_PI_AGENTS_CHILD", value: "1" }];
+export function detectRole(env = process.env, hasTrackedAncestor = false, isInteractive = true, 
+/** SUBAGENT-REQ-002/003: built-in profiles' own child-env markers ONLY (never the user-configured one — see `configuredMarkers` below) — generalises the single hardcoded `GENTLE_PI_AGENTS_CHILD` check without changing precedence. See `domain/subagent-profile.ts#builtinChildMarkers`. */
+childMarkers = DEFAULT_CHILD_MARKERS, 
+/** C2: the user-configured profile's child-env marker(s) only (`KANKAKU_SUBAGENT_CHILD_ENV`, already denylist-filtered by `loadConfig`) — a SEPARATE, weaker tier: it can confirm a subagent, but unlike `childMarkers` above, never demotes an interactive session. See `domain/subagent-profile.ts#configuredChildMarkers`. */
+configuredMarkers = []) {
+    if (matchesAnyMarker(env, childMarkers))
+        return { role: "subagent" };
+    const configuredMatch = matchesAnyMarker(env, configuredMarkers);
+    if (configuredMatch && !isInteractive)
+        return { role: "subagent" };
+    let result;
+    const override = readRoleOverride(env);
+    if (override === "orchestrator") {
+        result = { role: "orchestrator" };
+    }
+    else if (override === "subagent") {
+        result = isInteractive ? { role: "orchestrator", overrideIgnoredInteractive: true } : { role: "subagent" };
+    }
+    else if (hasTrackedAncestor && !isInteractive) {
+        result = { role: "orchestrator", roleConfidence: "uncertain" };
+    }
+    else {
+        result = { role: "orchestrator" };
+    }
+    // The configured marker matched but was ignored (this process is
+    // interactive) — flagged regardless of what else decided `result`, so the
+    // caller always learns a configured marker is present-but-ambient here.
+    return configuredMatch && isInteractive ? { ...result, configuredMarkerIgnoredInteractive: true } : result;
+}
+/** Read `KANKAKU_PB_URL`/`KANKAKU_PB_EMAIL`/`KANKAKU_PB_PASSWORD`. Empty/whitespace-only values are treated as absent. */
+export function loadHubEnvCredentials(env = process.env) {
+    return {
+        url: env["KANKAKU_PB_URL"]?.trim() || undefined,
+        email: env["KANKAKU_PB_EMAIL"]?.trim() || undefined,
+        password: env["KANKAKU_PB_PASSWORD"]?.trim() || undefined,
+    };
+}
+/** `KANKAKU_MACHINE`, or `hostname()` when unset/blank. Injected so this stays testable without touching `os.hostname`. */
+export function loadMachine(env, hostname) {
+    return env["KANKAKU_MACHINE"]?.trim() || hostname();
+}
+/** Hosts allowed to use a plain-HTTP hub URL. */
+function isLocalHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+}
+const VALID_PROMPT_MODES = new Set(["none", "truncated", "full"]);
+const DEFAULT_SYNC_WINDOW_HOURS = 24;
+const DEFAULT_SYNC_MIN_INTERVAL_MINUTES = 5;
+export function loadSyncConfig(env = process.env) {
+    const promptRaw = env["KANKAKU_SYNC_PROMPT"]?.trim();
+    const promptMode = promptRaw && VALID_PROMPT_MODES.has(promptRaw) ? promptRaw : "none";
+    const windowRaw = env["KANKAKU_SYNC_WINDOW_HOURS"]?.trim();
+    const parsedWindow = windowRaw ? Number(windowRaw) : NaN;
+    const windowHours = Number.isFinite(parsedWindow) && parsedWindow > 0 ? parsedWindow : DEFAULT_SYNC_WINDOW_HOURS;
+    const syncRecords = env["KANKAKU_SYNC_RECORDS"]?.trim() !== "0";
+    const auto = env["KANKAKU_SYNC_AUTO"]?.trim() !== "0";
+    // 0 is a valid, explicit "disable throttling" value, distinct from an
+    // unset or garbage one (which falls back to the default) — unlike
+    // windowHours above, which treats 0 as invalid.
+    const minIntervalRaw = env["KANKAKU_SYNC_MIN_INTERVAL_MINUTES"]?.trim();
+    const parsedMinInterval = minIntervalRaw ? Number(minIntervalRaw) : NaN;
+    const minIntervalMinutes = Number.isFinite(parsedMinInterval) && parsedMinInterval >= 0 ? parsedMinInterval : DEFAULT_SYNC_MIN_INTERVAL_MINUTES;
+    return { promptMode, windowHours, syncRecords, auto, minIntervalMinutes };
+}
+/**
+ * A hub URL must be HTTPS, unless it points at localhost/127.0.0.1/::1 (a
+ * local PocketBase instance for development). Also rejects a URL that does
+ * not parse at all.
+ */
+export function validateHubUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: `kankaku: invalid hub URL: ${url}` };
+    }
+    if (parsed.protocol === "https:")
+        return { ok: true };
+    if (parsed.protocol === "http:" && isLocalHost(parsed.hostname))
+        return { ok: true };
+    return { ok: false, reason: `kankaku: refusing non-HTTPS hub URL (only localhost is allowed over plain HTTP): ${url}` };
+}

package/dist/domain/ancestry-match.d.ts

@@ -0,0 +1,49 @@
+import type { RegistryEntry } from "../ports/process-registry.ts";
+import type { OrchestratorRef } from "./work-record.ts";
+/**
+ * Max allowed drift (ms) between a live process's freshly re-derived start
+ * identity and the one recorded in its registry entry. Absorbs
+ * second-granularity rounding/reading noise from the underlying OS
+ * start-time source (`adapters/ancestry.ts`) — not a measure of real clock
+ * error, since both readings of the *same* process instance stay tightly
+ * consistent regardless of that source's own precision (see that module's
+ * docs). A genuine pid-reuse produces a gap far larger than this.
+ */
+export declare const START_ID_TOLERANCE_MS = 2000;
+/**
+ * The nearest tracked ancestor whose identity can actually be *proven*: the
+ * first `ancestryPids` entry (ordered nearest-parent first, see
+ * `adapters/ancestry.ts#walkAncestry`) that has a matching
+ * {@link RegistryEntry} AND whose registry-recorded `processStartId`
+ * agrees, within {@link START_ID_TOLERANCE_MS}, with `liveStartId(pid)` —
+ * a fresh re-derivation of that same pid's actual OS start time, taken
+ * from the same ancestry snapshot the caller already has. Matching by pid
+ * number alone is not safe: the OS reuses pids, so a stale entry left
+ * behind by a dead, never-cleaned-up process can otherwise be
+ * misattributed to whatever unrelated live process the kernel later hands
+ * that same pid to (a genuine top-level session silently misclassified as
+ * someone's subagent forever). A candidate whose identity cannot be
+ * verified — no `processStartId` on the entry (legacy/malformed), or no
+ * live start id available for that pid (platform without ancestor-chain
+ * support, or a snapshot gap) — is never matched; the walk continues past
+ * it exactly like an untracked hop, so a further genuine ancestor can still
+ * be found. Returns `undefined` when no ancestor pid is trackable at all —
+ * callers must treat that exactly like "no registry available" (safe
+ * fallback to the pre-registry behaviour), never invent a match.
+ */
+export declare function findAncestorEntry(ancestryPids: number[], entries: RegistryEntry[], liveStartId: (pid: number) => number | undefined): RegistryEntry | undefined;
+/**
+ * Resolve the ultimate, top-level {@link OrchestratorRef} for `ancestorEntry`
+ * (the nearest verified ancestor {@link findAncestorEntry} returned) — F4's
+ * nested-subagent fix. When that ancestor is itself a `subagent`-role entry
+ * that already resolved its own verified `orchestratorRef` (a
+ * subagent-of-subagent chain: this process's parent is itself someone's
+ * child), that inherited ref is returned instead of one built from the
+ * ancestor's own identity — so a grandchild's `orchestratorRef` (and, via
+ * its `dir`, `extension.ts`'s F1 write-routing target) always points at
+ * the real top-level orchestrator, never a middle hop. Falls back to an
+ * ancestor's own identity when it is an orchestrator, or a subagent that
+ * never resolved a ref of its own (e.g. it discovered no tracked ancestor
+ * at its own startup) — never invents one. `undefined` in, `undefined` out.
+ */
+export declare function resolveOrchestratorRef(ancestorEntry: RegistryEntry | undefined): OrchestratorRef | undefined;

package/dist/domain/ancestry-match.js

@@ -0,0 +1,82 @@
+/**
+ * Max allowed drift (ms) between a live process's freshly re-derived start
+ * identity and the one recorded in its registry entry. Absorbs
+ * second-granularity rounding/reading noise from the underlying OS
+ * start-time source (`adapters/ancestry.ts`) — not a measure of real clock
+ * error, since both readings of the *same* process instance stay tightly
+ * consistent regardless of that source's own precision (see that module's
+ * docs). A genuine pid-reuse produces a gap far larger than this.
+ */
+export const START_ID_TOLERANCE_MS = 2000;
+/** Whether two start identities are close enough to be the same process instance. `undefined` on either side is always "no", never a coincidental match. */
+function sameProcessInstance(recorded, live) {
+    if (recorded === undefined || live === undefined)
+        return false;
+    return Math.abs(recorded - live) <= START_ID_TOLERANCE_MS;
+}
+/**
+ * The nearest tracked ancestor whose identity can actually be *proven*: the
+ * first `ancestryPids` entry (ordered nearest-parent first, see
+ * `adapters/ancestry.ts#walkAncestry`) that has a matching
+ * {@link RegistryEntry} AND whose registry-recorded `processStartId`
+ * agrees, within {@link START_ID_TOLERANCE_MS}, with `liveStartId(pid)` —
+ * a fresh re-derivation of that same pid's actual OS start time, taken
+ * from the same ancestry snapshot the caller already has. Matching by pid
+ * number alone is not safe: the OS reuses pids, so a stale entry left
+ * behind by a dead, never-cleaned-up process can otherwise be
+ * misattributed to whatever unrelated live process the kernel later hands
+ * that same pid to (a genuine top-level session silently misclassified as
+ * someone's subagent forever). A candidate whose identity cannot be
+ * verified — no `processStartId` on the entry (legacy/malformed), or no
+ * live start id available for that pid (platform without ancestor-chain
+ * support, or a snapshot gap) — is never matched; the walk continues past
+ * it exactly like an untracked hop, so a further genuine ancestor can still
+ * be found. Returns `undefined` when no ancestor pid is trackable at all —
+ * callers must treat that exactly like "no registry available" (safe
+ * fallback to the pre-registry behaviour), never invent a match.
+ */
+export function findAncestorEntry(ancestryPids, entries, liveStartId) {
+    if (ancestryPids.length === 0 || entries.length === 0)
+        return undefined;
+    const byPid = new Map();
+    for (const entry of entries) {
+        // First entry for a given pid wins; a pid should only ever have one
+        // live registry file, but a torn write racing a sweep could in theory
+        // leave two candidates behind — deterministic tie-break, not correctness-critical.
+        if (!byPid.has(entry.pid))
+            byPid.set(entry.pid, entry);
+    }
+    for (const pid of ancestryPids) {
+        const entry = byPid.get(pid);
+        if (!entry)
+            continue;
+        if (sameProcessInstance(entry.processStartId, liveStartId(pid)))
+            return entry;
+        // Either unprovable, or this pid has genuinely been reused by a
+        // different process instance since the entry was written: not our
+        // ancestor. Keep walking — a further, verifiable ancestor may still exist.
+    }
+    return undefined;
+}
+/**
+ * Resolve the ultimate, top-level {@link OrchestratorRef} for `ancestorEntry`
+ * (the nearest verified ancestor {@link findAncestorEntry} returned) — F4's
+ * nested-subagent fix. When that ancestor is itself a `subagent`-role entry
+ * that already resolved its own verified `orchestratorRef` (a
+ * subagent-of-subagent chain: this process's parent is itself someone's
+ * child), that inherited ref is returned instead of one built from the
+ * ancestor's own identity — so a grandchild's `orchestratorRef` (and, via
+ * its `dir`, `extension.ts`'s F1 write-routing target) always points at
+ * the real top-level orchestrator, never a middle hop. Falls back to an
+ * ancestor's own identity when it is an orchestrator, or a subagent that
+ * never resolved a ref of its own (e.g. it discovered no tracked ancestor
+ * at its own startup) — never invents one. `undefined` in, `undefined` out.
+ */
+export function resolveOrchestratorRef(ancestorEntry) {
+    if (ancestorEntry === undefined)
+        return undefined;
+    if (ancestorEntry.role === "subagent" && ancestorEntry.orchestratorRef !== undefined) {
+        return ancestorEntry.orchestratorRef;
+    }
+    return { pid: ancestorEntry.pid, project: ancestorEntry.project, startedAt: ancestorEntry.startedAt, dir: ancestorEntry.dir };
+}

package/dist/domain/client-label.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+export interface ClientSources {
+    /** Set for the current pi session via `/kankaku client <name>`. Highest precedence. */
+    session?: string;
+    /** From the `KANKAKU_CLIENT` environment variable. */
+    env?: string;
+    /** From the project's `.kankaku/config.json`. Lowest precedence. */
+    project?: string;
+}
+export type ClientSourceName = "session" | "env" | "project";
+/** `true` when `value` is a non-empty, safe client name. */
+export declare function isValidClient(value: string): boolean;
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export declare function resolveClient(sources: ClientSources): string | undefined;
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export declare function resolveClientSource(sources: ClientSources): ClientSourceName | undefined;

package/dist/domain/client-label.js

@@ -0,0 +1,44 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+/** Safe client name: letters, digits, `.`, `_`, `-`, 1-64 chars. */
+const CLIENT_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** Property names that behave specially on a plain object; never usable as a client name. */
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+/** `true` when `value` is a non-empty, safe client name. */
+export function isValidClient(value) {
+    return CLIENT_PATTERN.test(value) && !RESERVED_NAMES.has(value);
+}
+/** Trim and validate a candidate client name; `undefined` when absent or invalid. */
+function normalize(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return isValidClient(trimmed) ? trimmed : undefined;
+}
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export function resolveClient(sources) {
+    return normalize(sources.session) ?? normalize(sources.env) ?? normalize(sources.project);
+}
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export function resolveClientSource(sources) {
+    if (normalize(sources.session) !== undefined)
+        return "session";
+    if (normalize(sources.env) !== undefined)
+        return "env";
+    if (normalize(sources.project) !== undefined)
+        return "project";
+    return undefined;
+}

package/dist/domain/day.d.ts

@@ -0,0 +1,2 @@
+/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
+export declare function localDay(iso: string): string;

package/dist/domain/day.js

@@ -0,0 +1,8 @@
+/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
+export function localDay(iso) {
+    const date = new Date(iso);
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}

package/dist/domain/export.d.ts

@@ -0,0 +1,38 @@
+import type { WorkStatus } from "./work-record.ts";
+import type { TaskView } from "./task-view.ts";
+/** One flat, spreadsheet-friendly row per {@link TaskView}. */
+export interface ExportRow {
+    id: string;
+    /** Local calendar day (`YYYY-MM-DD`) the task started on. */
+    day: string;
+    startedAt: string;
+    endedAt: string;
+    /** Empty string when the task has no resolved client. */
+    client: string;
+    /** Empty string when the orchestrator record has no session name. */
+    sessionName: string;
+    /** Empty string when the orchestrator record has no session id. */
+    sessionId: string;
+    project: string;
+    status: WorkStatus;
+    /** First 200 chars of the task's prompt, with newlines collapsed to spaces. */
+    prompt: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    cost: number;
+    tokensIn: number;
+    tokensOut: number;
+    cacheRead: number;
+    subagentCount: number;
+    /** JSON-encoded `TaskView.segments` map. */
+    segments: string;
+    /** Empty string when the orchestrator record has no model. */
+    model: string;
+}
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export declare function exportRows(tasks: TaskView[]): ExportRow[];
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export declare function toCsv(rows: ExportRow[]): string;
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export declare function toJson(rows: ExportRow[]): string;