kankaku 0.5.0 → 0.6.0

package/dist/adapters/sync-runner.js

@@ -0,0 +1,242 @@
+/**
+ * Orchestrates one sync run: read every record, build tasks (never
+ * re-implementing the aggregation — `buildTasks` is the only place it
+ * lives), plan what needs pushing, push it, and persist the new state.
+ * Never throws to its caller: every failure mode is folded into the
+ * returned {@link SyncSummary}.
+ */
+import { buildTasks } from "../domain/task-view.js";
+import { computeTaskContentHash, planSync, pruneHashes } from "../domain/sync-plan.js";
+const NO_LABEL = "(no label)";
+const DEFAULT_MIN_AUTO_INTERVAL_MS = 5 * 60 * 1000;
+/** The later of two ISO timestamps, treating `undefined` as earlier than anything. */
+function laterIso(a, b) {
+    if (a === undefined)
+        return b;
+    return Date.parse(b) > Date.parse(a) ? b : a;
+}
+function emptySummary(durationMs, syncedThrough) {
+    return { uploaded: 0, updated: 0, skipped: 0, failed: [], unassigned: {}, syncedThrough, durationMs };
+}
+/**
+ * Whether the automatic path's throttle should block this run right now.
+ * Only `agent_settled` — fired once per prompt, far more often than a
+ * session starts or ends — is ever throttled; `session_start` and
+ * `session_shutdown` always bypass it (a session boundary is a good time
+ * to catch up regardless of how recently the last automatic run happened,
+ * and the shutdown one is awaited and time-bounded on its own — see
+ * `adapters/pi-tracker.ts`). `undefined`/non-finite `lastRunAt` (never
+ * run, or a malformed on-disk value) never throttles either — there is
+ * nothing to measure the interval against.
+ */
+function isThrottled(state, trigger, now, minIntervalMs) {
+    if (trigger !== "agent_settled")
+        return false;
+    if (minIntervalMs <= 0)
+        return false;
+    const lastRunAt = state?.lastRunAt;
+    if (!Number.isFinite(lastRunAt))
+        return false;
+    if (now - lastRunAt >= minIntervalMs)
+        return false;
+    return true;
+}
+/**
+ * Run one sync pass. Acquires the cross-process lock for the whole run
+ * (never held across `await` boundaries outside this function) so two pi
+ * processes never race on the same `sync-state.json`.
+ *
+ * When `options.trigger` is set (the automatic `session_start`/
+ * `agent_settled`/`session_shutdown` path, as opposed to a manual
+ * `/kankaku sync`), two cheap gates run before any `WorkLog.readAll()` or
+ * network call: (a) if the log's `version()` is unchanged since the last
+ * successful sync and that sync did not error, skip entirely, for every
+ * trigger; otherwise (b) throttle to at most one real attempt per
+ * `minAutoIntervalMs`, but only for `agent_settled` — fired once per
+ * prompt, so `version()` almost always differs right after it appended a
+ * record. `session_start` and `session_shutdown` never throttle (see
+ * `isThrottled`). Neither gate ever applies to a manual sync.
+ */
+export async function runSync(deps, options = {}) {
+    const startedAt = deps.clock.now();
+    if (options.trigger !== undefined) {
+        const peek = deps.stateStore.read();
+        const currentVersion = deps.log.version?.();
+        const versionUnchanged = currentVersion !== undefined && peek?.logVersion === currentVersion;
+        if (versionUnchanged && peek?.lastError === undefined) {
+            return emptySummary(deps.clock.now() - startedAt, peek?.syncedThrough);
+        }
+        const minIntervalMs = deps.minAutoIntervalMs ?? DEFAULT_MIN_AUTO_INTERVAL_MS;
+        if (isThrottled(peek, options.trigger, deps.clock.now(), minIntervalMs)) {
+            return emptySummary(deps.clock.now() - startedAt, peek?.syncedThrough);
+        }
+    }
+    let lockAcquired = false;
+    try {
+        lockAcquired = deps.stateStore.tryLock();
+        if (!lockAcquired) {
+            const state = deps.stateStore.read();
+            return { ...emptySummary(deps.clock.now() - startedAt, state?.syncedThrough), locked: true };
+        }
+        const state = deps.stateStore.read();
+        // Captured once, here, and persisted as-is below: this is the version
+        // the tasks below were actually built from, not whatever the log might
+        // become by the time an awaited push finishes.
+        const logVersionAtRead = deps.log.version?.();
+        const tasks = buildTasks(deps.log.readAll());
+        const plan = planSync(tasks, state, { target: deps.target, ...(deps.windowHours !== undefined ? { windowHours: deps.windowHours } : {}), ...(options.full !== undefined ? { full: options.full } : {}) });
+        let results;
+        try {
+            results = await deps.sink.push(plan.toSync);
+        }
+        catch (error) {
+            // WorkSink implementations are expected never to throw, but this
+            // runner must hold that guarantee even if one does.
+            const message = error instanceof Error ? error.message : String(error);
+            const summary = emptySummary(deps.clock.now() - startedAt, state?.syncedThrough);
+            summary.skipped = plan.unchangedCount;
+            summary.error = message;
+            persistError(deps, state, message, logVersionAtRead);
+            return summary;
+        }
+        const byId = new Map(plan.toSync.map((task) => [task.id, task]));
+        // Both are keyed by content that ultimately traces back to free-text
+        // worklog/legacy-client data (task ids, legacy client labels): built in
+        // a `Map` and emitted via `Object.fromEntries` below (never
+        // `newHashes[task.id] = ...` on a plain object), so a value like
+        // `__proto__` or `constructor` becomes a normal own entry instead of
+        // silently colliding with an inherited `Object.prototype` property.
+        const newHashes = new Map();
+        const failed = [];
+        const unassigned = new Map();
+        let uploaded = 0;
+        let updated = 0;
+        let syncedThrough = state?.syncedThrough;
+        let stopError;
+        // Whether at least one task was actually resolved (pushed or recorded
+        // as failed) this run — as opposed to the run stopping on its very
+        // first attempt. Guards `target` below: a run against a new/unreachable
+        // target that resolves nothing must not overwrite the state's `target`,
+        // or a later sync against the *real* target would wrongly see it as
+        // unchanged and skip the full re-evaluation it needs.
+        let progressed = false;
+        for (const result of results) {
+            const task = byId.get(result.taskId);
+            if (!task)
+                continue; // defensive: a WorkSink implementation misbehaving should not crash the runner.
+            if (result.outcome.kind === "created" || result.outcome.kind === "updated") {
+                if (result.outcome.kind === "created")
+                    uploaded += 1;
+                else
+                    updated += 1;
+                newHashes.set(task.id, computeTaskContentHash(task));
+                syncedThrough = laterIso(syncedThrough, task.endedAt);
+                progressed = true;
+                if (result.outcome.unassigned) {
+                    const label = result.outcome.legacyLabel || NO_LABEL;
+                    unassigned.set(label, (unassigned.get(label) ?? 0) + 1);
+                }
+            }
+            else if (result.outcome.kind === "failed") {
+                // Recorded and skipped, not retried forever: stamp its hash too so
+                // an unchanged, permanently-invalid task is not resent every run.
+                failed.push({ id: task.id, reason: result.outcome.reason });
+                newHashes.set(task.id, computeTaskContentHash(task));
+                syncedThrough = laterIso(syncedThrough, task.endedAt);
+                progressed = true;
+            }
+            else {
+                // "error": a network/timeout/5xx/auth failure. Stop here — nothing
+                // after this point in the (chronologically sorted) results is
+                // considered resolved, so syncedThrough does not advance past it.
+                stopError = result.outcome.reason;
+                break;
+            }
+        }
+        const mergedHashes = { ...(state?.hashes ?? {}), ...Object.fromEntries(newHashes) };
+        // G2: no longer window-bound — see `domain/sync-plan.ts#pruneHashes`'s
+        // doc comment. `tasks` here is every task `buildTasks` currently knows
+        // about (the full `readAll()`, not just this run's eligible/window
+        // subset), so a hash is only ever dropped for a task id that has
+        // genuinely vanished, never merely because it is old.
+        const prunedHashes = pruneHashes(mergedHashes, tasks);
+        // Only adopt deps.target as the persisted target once this run has
+        // actually resolved something against it; otherwise keep whatever
+        // target (if any) the previous state was synced against.
+        const persistedTarget = progressed || state === undefined ? deps.target : state.target;
+        deps.stateStore.write({
+            target: persistedTarget,
+            ...(syncedThrough !== undefined ? { syncedThrough } : {}),
+            hashes: prunedHashes,
+            ...(stopError !== undefined ? { lastError: { message: stopError, at: new Date(deps.clock.now()).toISOString() } } : {}),
+            ...(logVersionAtRead !== undefined ? { logVersion: logVersionAtRead } : {}),
+            lastRunAt: deps.clock.now(),
+        });
+        return {
+            uploaded,
+            updated,
+            skipped: plan.unchangedCount,
+            failed,
+            unassigned: Object.fromEntries(unassigned),
+            syncedThrough,
+            durationMs: deps.clock.now() - startedAt,
+            ...(stopError !== undefined ? { error: stopError } : {}),
+        };
+    }
+    finally {
+        if (lockAcquired)
+            deps.stateStore.unlock();
+    }
+}
+function persistError(deps, state, message, logVersionAtRead) {
+    deps.stateStore.write({
+        target: deps.target,
+        ...(state?.syncedThrough !== undefined ? { syncedThrough: state.syncedThrough } : {}),
+        hashes: state?.hashes ?? {},
+        lastError: { message, at: new Date(deps.clock.now()).toISOString() },
+        ...(logVersionAtRead !== undefined ? { logVersion: logVersionAtRead } : {}),
+        lastRunAt: deps.clock.now(),
+    });
+}
+/** Number of tasks pending a sync right now, for `/kankaku sync status` — computed locally, no network. */
+export function pendingCount(tasks, state, target, windowHours) {
+    const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
+    return plan.toSync.length + plan.correctionsDeferred;
+}
+/**
+ * `/kankaku sync status`: the persisted state, a locally-computed pending
+ * count, and (R3) how many tasks changed since their last sync but fall
+ * outside this run's revisit window — a `sync all` needed to pick them up
+ * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
+ * (PocketBase)" > "Sync" > "Limitations"). No network.
+ */
+export function computeSyncStatus(log, stateStore, target, windowHours) {
+    const state = stateStore.read();
+    const tasks = buildTasks(log.readAll());
+    const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
+    // Deferred corrections are pending too: the cap only spreads them over runs.
+    return { state, pending: plan.toSync.length + plan.correctionsDeferred, staleOutsideWindow: plan.staleOutsideWindow.length };
+}
+/**
+ * Wrap an async function so concurrent callers share one in-flight call
+ * instead of starting a new one each — kankaku's single-flight guard for
+ * sync: `/kankaku sync`, the `session_start` auto-sync and the
+ * `agent_settled` auto-sync all go through the same wrapped function, so
+ * only one sync is ever running at a time within this process. (The
+ * cross-process case is covered separately by `SyncStateStore`'s lock
+ * file.) A caller that arrives while one is in flight joins its result
+ * rather than queuing a fresh run — the next trigger (the next
+ * `session_start` or `agent_settled`) will pick up anything missed, since
+ * every sync also revisits the trailing window.
+ */
+export function singleFlight(fn) {
+    let inFlight;
+    return (...args) => {
+        if (!inFlight) {
+            inFlight = fn(...args).finally(() => {
+                inFlight = undefined;
+            });
+        }
+        return inFlight;
+    };
+}

package/dist/adapters/sync-state-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Disk-backed store for `<KANKAKU_DIR>/sync-state.json`, plus a simple
+ * cross-process lock so two pi processes (e.g. an orchestrator's
+ * auto-sync and a manual `/kankaku sync` in another terminal) never sync
+ * the same directory concurrently. Mirrors `file-inflight-store.ts`'s
+ * atomic-write and liveness-probe conventions.
+ */
+import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import type { SyncState } from "../domain/sync-plan.ts";
+/** The subset of `node:fs` the lock's acquire/recover path needs, injectable so tests can simulate cross-process interleaving deterministically. */
+export interface SyncStateStoreFsOps {
+    existsSync: typeof existsSync;
+    readFileSync: typeof readFileSync;
+    writeFileSync: typeof writeFileSync;
+    renameSync: typeof renameSync;
+    unlinkSync: typeof unlinkSync;
+    openSync: typeof openSync;
+    closeSync: typeof closeSync;
+}
+export interface SyncStateStoreDeps {
+    dir: string;
+    pid: number;
+    /** Whether a pid is still alive. Defaults to the same signal-probe used elsewhere. */
+    isAlive?: (pid: number) => boolean;
+    /** Injectable for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable `node:fs` primitives for the lock's acquire/recover path. Defaults to the real ones. */
+    fs?: SyncStateStoreFsOps;
+}
+/**
+ * `read()`/`write()` tolerate a missing or malformed file (return
+ * `undefined` / overwrite, respectively) since this state is disposable —
+ * losing it only costs a full re-evaluation on the next sync, never data.
+ * `tryLock()`/`unlock()` implement a simple pid+timestamp lock file, stale
+ * after {@link STALE_LOCK_MS}.
+ */
+export declare class SyncStateStore {
+    private readonly deps;
+    constructor(deps: SyncStateStoreDeps);
+    private get statePath();
+    private get lockPath();
+    read(): SyncState | undefined;
+    write(state: SyncState): void;
+    /**
+     * Try to acquire the cross-process sync lock. Acquisition itself is
+     * atomic: it always goes through an exclusive create ({@link acquireFresh},
+     * `open` with the `wx` flag), never a read-then-write, so two processes
+     * racing to create the lock file can never both succeed. Returns `true`
+     * (and takes ownership) when there is no lock file, this process already
+     * owns it (re-entrant), or the existing one is stale (its pid is no
+     * longer alive, or it is older than {@link STALE_LOCK_MS}) and this
+     * process wins the race to recover it; `false` when a live, fresh lock is
+     * held by another process, or this process loses a stale-lock recovery
+     * race to another one.
+     */
+    tryLock(): boolean;
+    /** Create the lock file exclusively (`wx`): fails with EEXIST when another lock already exists, never silently overwrites one. Assumes `this.deps.dir` already exists (`tryLock` ensures it once up front). */
+    private acquireFresh;
+    /** Release the lock, but only if this process still owns it (never clobber someone else's fresher lock). */
+    unlock(): void;
+    private readLock;
+}

package/dist/adapters/sync-state-store.js

@@ -0,0 +1,188 @@
+/**
+ * Disk-backed store for `<KANKAKU_DIR>/sync-state.json`, plus a simple
+ * cross-process lock so two pi processes (e.g. an orchestrator's
+ * auto-sync and a manual `/kankaku sync` in another terminal) never sync
+ * the same directory concurrently. Mirrors `file-inflight-store.ts`'s
+ * atomic-write and liveness-probe conventions.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const STATE_FILE_NAME = "sync-state.json";
+const LOCK_FILE_NAME = "sync.lock";
+/** A lock older than this is considered abandoned even if its owning pid still (coincidentally) exists. */
+const STALE_LOCK_MS = 5 * 60 * 1000;
+const defaultFsOps = { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, openSync, closeSync };
+function isEnoent(error) {
+    return error?.code === "ENOENT";
+}
+function isEexist(error) {
+    return error?.code === "EEXIST";
+}
+function isSyncState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record["target"] === "string" &&
+        typeof record["hashes"] === "object" &&
+        record["hashes"] !== null &&
+        (record["syncedThrough"] === undefined || typeof record["syncedThrough"] === "string"));
+}
+function isLockFile(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record["pid"] === "number" && typeof record["at"] === "number";
+}
+function atomicWrite(filePath, content) {
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, filePath);
+}
+function safeUnlink(fs, filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // Best effort: already removed, or never existed.
+    }
+}
+/**
+ * `read()`/`write()` tolerate a missing or malformed file (return
+ * `undefined` / overwrite, respectively) since this state is disposable —
+ * losing it only costs a full re-evaluation on the next sync, never data.
+ * `tryLock()`/`unlock()` implement a simple pid+timestamp lock file, stale
+ * after {@link STALE_LOCK_MS}.
+ */
+export class SyncStateStore {
+    deps;
+    constructor(deps) {
+        this.deps = {
+            dir: deps.dir,
+            pid: deps.pid,
+            isAlive: deps.isAlive ?? defaultIsAlive,
+            now: deps.now ?? (() => Date.now()),
+            fs: deps.fs ?? defaultFsOps,
+        };
+    }
+    get statePath() {
+        return join(this.deps.dir, STATE_FILE_NAME);
+    }
+    get lockPath() {
+        return join(this.deps.dir, LOCK_FILE_NAME);
+    }
+    read() {
+        try {
+            if (!existsSync(this.statePath))
+                return undefined;
+            const parsed = JSON.parse(readFileSync(this.statePath, "utf8"));
+            return isSyncState(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(state) {
+        mkdirSync(this.deps.dir, { recursive: true });
+        atomicWrite(this.statePath, JSON.stringify(state));
+    }
+    /**
+     * Try to acquire the cross-process sync lock. Acquisition itself is
+     * atomic: it always goes through an exclusive create ({@link acquireFresh},
+     * `open` with the `wx` flag), never a read-then-write, so two processes
+     * racing to create the lock file can never both succeed. Returns `true`
+     * (and takes ownership) when there is no lock file, this process already
+     * owns it (re-entrant), or the existing one is stale (its pid is no
+     * longer alive, or it is older than {@link STALE_LOCK_MS}) and this
+     * process wins the race to recover it; `false` when a live, fresh lock is
+     * held by another process, or this process loses a stale-lock recovery
+     * race to another one.
+     */
+    tryLock() {
+        mkdirSync(this.deps.dir, { recursive: true });
+        if (this.acquireFresh())
+            return true;
+        const existing = this.readLock();
+        if (!existing) {
+            // Raced with a release between our failed create and this read; the
+            // slot may be free again now. One more attempt, then give up rather
+            // than looping forever.
+            return this.acquireFresh();
+        }
+        if (existing.pid === this.deps.pid)
+            return true; // re-entrant: we already own it.
+        const age = this.deps.now() - existing.at;
+        const stale = age > STALE_LOCK_MS || !this.deps.isAlive(existing.pid);
+        if (!stale)
+            return false; // live, fresh lock held by someone else.
+        // Stale-lock recovery, made race-safe: rename the stale file to a
+        // unique tombstone name first. `rename` is atomic, so only one racer's
+        // call can succeed; every loser gets ENOENT and backs off instead of
+        // deleting (or overwriting) a lock it never proved was still stale.
+        const tombstone = `${this.lockPath}.stale.${this.deps.pid}.${this.deps.now()}.tmp`;
+        try {
+            this.deps.fs.renameSync(this.lockPath, tombstone);
+        }
+        catch (error) {
+            if (isEnoent(error))
+                return false; // lost the recovery race; back off.
+            throw error;
+        }
+        safeUnlink(this.deps.fs, tombstone);
+        return this.acquireFresh(); // false here means a third racer won it first.
+    }
+    /** Create the lock file exclusively (`wx`): fails with EEXIST when another lock already exists, never silently overwrites one. Assumes `this.deps.dir` already exists (`tryLock` ensures it once up front). */
+    acquireFresh() {
+        let fd;
+        try {
+            fd = this.deps.fs.openSync(this.lockPath, "wx");
+        }
+        catch (error) {
+            if (isEexist(error))
+                return false;
+            throw error;
+        }
+        try {
+            this.deps.fs.writeFileSync(fd, JSON.stringify({ pid: this.deps.pid, at: this.deps.now() }));
+        }
+        catch (error) {
+            try {
+                this.deps.fs.closeSync(fd);
+            }
+            catch {
+                // Best effort: still try to clean up the partially written file below.
+            }
+            safeUnlink(this.deps.fs, this.lockPath);
+            throw error;
+        }
+        this.deps.fs.closeSync(fd);
+        return true;
+    }
+    /** Release the lock, but only if this process still owns it (never clobber someone else's fresher lock). */
+    unlock() {
+        const existing = this.readLock();
+        if (existing && existing.pid === this.deps.pid) {
+            safeUnlink(this.deps.fs, this.lockPath);
+        }
+    }
+    readLock() {
+        try {
+            if (!this.deps.fs.existsSync(this.lockPath))
+                return undefined;
+            const parsed = JSON.parse(this.deps.fs.readFileSync(this.lockPath, "utf8"));
+            return isLockFile(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Default `isAlive`: probe with signal 0 — mirrors `pi-tracker.ts`'s default. */
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,168 @@
+import type { SegmentRule } from "./domain/segment-rule.ts";
+import type { PromptPrivacyMode } from "./domain/hub-entry.ts";
+import type { ChildEnvMarker, SubagentProfile } from "./domain/subagent-profile.ts";
+export interface KankakuConfig {
+    /** Directory for the work log, relative to the project cwd unless absolute. */
+    dir: string;
+    /** Tool names whose execution span counts as waiting time. */
+    interactiveTools: string[];
+    /**
+     * Every active {@link SubagentProfile} (ADR 0020): the built-ins
+     * (gentle-pi, pi's bundled reference example, pi-subagents) plus, when
+     * `KANKAKU_SUBAGENT_TOOLS`/`KANKAKU_SUBAGENT_CHILD_ENV` are set, one
+     * additional `"configured"` profile — always additive, never replacing
+     * gentle-pi's own recognition. `SUBAGENT_TOOL` is no longer a hardcoded
+     * constant; `domain/work-tracker.ts` matches subagent tool calls against
+     * the union of every profile's `toolNames`.
+     */
+    subagentProfiles: SubagentProfile[];
+    /** Rules that tag a tool execution's span under a named segment (e.g. `review`). */
+    segmentRules: SegmentRule[];
+    /** Default billing client for this project, from `KANKAKU_CLIENT`. See `domain/client-label.ts`. */
+    client?: string;
+    /**
+     * C2 (CRITICAL fix): every `KANKAKU_SUBAGENT_CHILD_ENV` entry rejected by
+     * {@link validateSubagentChildEnvMarkers} — a marker name that looks like
+     * an ambient pi/shell/OS/npm environment variable, not a genuine
+     * child-only marker. Always present (empty when nothing was configured,
+     * or everything configured was accepted), so a caller never has to guard
+     * against it being `undefined`. `/kankaku doctor` and a one-time
+     * `ctx.ui.notify` are expected to surface this (see `adapters/pi-tracker.ts`).
+     */
+    rejectedSubagentChildEnvMarkers: RejectedChildEnvMarker[];
+}
+/** One `KANKAKU_SUBAGENT_CHILD_ENV` marker {@link validateSubagentChildEnvMarkers} rejected, with why. */
+export interface RejectedChildEnvMarker {
+    name: string;
+    reason: string;
+}
+/**
+ * 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 declare function validateSubagentChildEnvMarkers(markers: readonly ChildEnvMarker[]): {
+    accepted: ChildEnvMarker[];
+    rejected: RejectedChildEnvMarker[];
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): KankakuConfig;
+export interface RoleDetection {
+    role: "orchestrator" | "subagent";
+    /**
+     * Set only when this process could not be positively proven top-level
+     * (ADR 0022's four-state classification, applied on top of the still-
+     * binary `role`): no recognised child-env-marker matched, but a live
+     * tracked ancestor process was found via the machine-wide process
+     * registry, AND this process is not itself an interactive session (see
+     * `isInteractive` below — F3). See `domain/task-view.ts`'s
+     * `roleConfidence` handling.
+     */
+    roleConfidence?: "uncertain";
+    /**
+     * Set when `KANKAKU_ROLE=subagent` was present, with no confirmed child
+     * marker, but was ignored because this process looked interactive (see
+     * this function's precedence doc — R1). The caller (`extension.ts`) is
+     * expected to surface this once via `ctx.ui.notify` at `session_start`
+     * and report it in `/kankaku doctor`, so the contradiction is never
+     * silent.
+     */
+    overrideIgnoredInteractive?: true;
+    /**
+     * C2 item 2/3: set when a USER-CONFIGURED child-env marker
+     * (`KANKAKU_SUBAGENT_CHILD_ENV`, the `configuredMarkers` 5th param below)
+     * matched, but was ignored for this process's `role` because it looked
+     * interactive — a configured marker, unlike a BUILT-IN one, never demotes
+     * an interactive session (see this function's precedence doc). The
+     * caller is expected to surface this once (mirroring
+     * `overrideIgnoredInteractive`) via `ctx.ui.notify` and `/kankaku
+     * doctor`, and to escalate the wording when this process also has no
+     * tracked ancestor at all — the strongest signal the marker is genuinely
+     * ambient (C2 item 3's self-check), not a real subagent mechanism.
+     */
+    configuredMarkerIgnoredInteractive?: true;
+}
+export type RoleOverride = "orchestrator" | "subagent";
+/**
+ * `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 declare function readRoleOverride(env?: NodeJS.ProcessEnv): RoleOverride | 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 declare function stripRoleOverride(env: NodeJS.ProcessEnv): void;
+export declare function detectRole(env?: NodeJS.ProcessEnv, hasTrackedAncestor?: boolean, isInteractive?: boolean, 
+/** 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?: readonly ChildEnvMarker[], 
+/** 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?: readonly ChildEnvMarker[]): RoleDetection;
+/** Hub (PocketBase) credentials read from the environment; any field can be absent. */
+export interface HubEnvCredentials {
+    url?: string;
+    email?: string;
+    password?: string;
+}
+/** Read `KANKAKU_PB_URL`/`KANKAKU_PB_EMAIL`/`KANKAKU_PB_PASSWORD`. Empty/whitespace-only values are treated as absent. */
+export declare function loadHubEnvCredentials(env?: NodeJS.ProcessEnv): HubEnvCredentials;
+/** `KANKAKU_MACHINE`, or `hostname()` when unset/blank. Injected so this stays testable without touching `os.hostname`. */
+export declare function loadMachine(env: NodeJS.ProcessEnv, hostname: () => string): string;
+/** Hub sync (Phase 2) configuration, read from the environment. See README "Hub (PocketBase)" sync section. */
+export interface SyncConfig {
+    /** `KANKAKU_SYNC_PROMPT`. Defaults to `"none"` — the conservative default (proposal §8). */
+    promptMode: PromptPrivacyMode;
+    /** `KANKAKU_SYNC_WINDOW_HOURS`. Defaults to 24; falls back to the default for a non-positive or non-numeric value. */
+    windowHours: number;
+    /** `KANKAKU_SYNC_RECORDS`. Defaults to enabled; `"0"` disables uploading `work_records` children. */
+    syncRecords: boolean;
+    /** `KANKAKU_SYNC_AUTO`. Defaults to enabled; `"0"` disables every automatic sync: the fire-and-forget session_start/agent_settled ones and the awaited session_shutdown one. */
+    auto: boolean;
+    /**
+     * `KANKAKU_SYNC_MIN_INTERVAL_MINUTES`. How often the *automatic*
+     * (`session_start`/`agent_settled`) sync path is allowed to actually run
+     * a sync, at most. Defaults to 5; `0` disables throttling entirely. Never
+     * applies to a manual `/kankaku sync`, `sync all`, or `backfill`. See
+     * `adapters/sync-runner.ts#runSync`.
+     */
+    minIntervalMinutes: number;
+}
+export declare function loadSyncConfig(env?: NodeJS.ProcessEnv): SyncConfig;
+export type HubUrlValidation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 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 declare function validateHubUrl(url: string): HubUrlValidation;