kankaku-pi 1.0.0

package/dist/domain/subagent-profile.js

@@ -0,0 +1,418 @@
+function readGentleAgents(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const details = result.details;
+    if (!details || typeof details !== "object")
+        return undefined;
+    const gentleAgents = details.gentleAgents;
+    if (!gentleAgents || typeof gentleAgents !== "object")
+        return undefined;
+    return gentleAgents;
+}
+function stringField(source, key) {
+    const value = source?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * Read pi's generic, profile-agnostic nested-usage convention: the tool
+ * RESULT's own top-level `usage` field (never nested under a profile's
+ * custom `details`). Tolerant of a missing/malformed field or non-numeric
+ * members — returns `undefined` (not an empty object) when nothing usable
+ * was found, so "no usage reported" stays distinguishable from "usage
+ * reported as all-zero".
+ */
+function readStandardUsage(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const raw = result.usage;
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const usage = {};
+    const fields = ["input", "output", "cacheRead", "cacheWrite", "cost"];
+    for (const field of fields) {
+        const value = raw[field];
+        if (typeof value === "number" && Number.isFinite(value))
+            usage[field] = value;
+    }
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
+function readAgentModeArgs(args) {
+    const agent = stringField(args, "agent");
+    const mode = stringField(args, "mode");
+    return { ...(agent !== undefined ? { agent } : {}), ...(mode !== undefined ? { mode } : {}) };
+}
+/**
+ * gentle-pi (first-class, ADR 0020): the richest, most robust profile —
+ * explicit `taskId` join, live `status`, `mode` (task/background) and
+ * cross-worktree `cwd`, all read from `result.details.gentleAgents`
+ * exactly as `work-tracker.ts#extractTaskId` did before this module
+ * existed. Verified against gentle-pi 3.3.0 source
+ * (`extensions/gentle-agents.ts`, `lib/agents-protocol.ts`,
+ * `lib/agents-runner.ts`): its tool result never carries a top-level
+ * `usage` field (children are separate OS processes, cost tracked
+ * independently through the existing ancestry/registry join) — this
+ * profile therefore never reports `usage`, so 6c's forwarding never
+ * touches gentle-pi's numbers.
+ */
+export const GENTLE_PI_PROFILE = {
+    id: "gentle-pi",
+    toolNames: ["subagent_run"],
+    childEnvMarkers: [{ name: "GENTLE_PI_AGENTS_CHILD", value: "1" }],
+    joinKeyConfidence: "explicit-id",
+    readLaunchArgs: readAgentModeArgs,
+    readResult(result) {
+        const gentleAgents = readGentleAgents(result);
+        if (!gentleAgents)
+            return {};
+        const taskId = stringField(gentleAgents, "taskId");
+        const agent = stringField(gentleAgents, "agent");
+        const status = stringField(gentleAgents, "status");
+        const mode = stringField(gentleAgents, "mode");
+        const cwd = stringField(gentleAgents, "cwd");
+        return {
+            ...(taskId !== undefined ? { taskId } : {}),
+            ...(agent !== undefined ? { agent } : {}),
+            ...(status !== undefined ? { status } : {}),
+            ...(mode !== undefined ? { mode } : {}),
+            ...(cwd !== undefined ? { cwd } : {}),
+        };
+    },
+};
+/**
+ * pi's bundled reference example extension
+ * (`examples/extensions/subagent/index.ts`, tool `subagent`). Verified: its
+ * `spawn()` call passes no `env` option at all (the child simply inherits
+ * the parent's environment unmodified) — so it sets NO child-identifying
+ * env marker, and a child of this kind can only ever be recognised through
+ * ancestry (ADR 0020: "always starts uncertain"). Because it has no
+ * marker, it can never become a *confirmed* `role: "subagent"` record
+ * (see `resolveChildProfile`) and therefore can never be double-joined —
+ * safe to forward `usage` unconditionally.
+ */
+/**
+ * C1 investigation note (real-shape disambiguation, verified against the
+ * bundled reference example's actual source above): its real tool RESULT
+ * never actually sets a top-level `usage` field at all — every `execute()`
+ * return statement in `examples/extensions/subagent/index.ts` returns only
+ * `{content, details, isError?}`; nested-call usage lives per-result inside
+ * `details.results[].usage`, not where pi's documented convention (and
+ * `readStandardUsage` below) looks. `pi-subagents` (npm, verified against
+ * 0.28.0 `src/runs/foreground/subagent-executor.ts` and
+ * `src/runs/foreground/execution.ts`) is the same: no `execute()` return
+ * anywhere in that package sets a top-level `usage` either. So for BOTH
+ * real packages examined, `readStandardUsage(result)` returns `undefined`
+ * today regardless of which one actually answered the call — this
+ * profile's generic top-level-`usage` read exists for pi's DOCUMENTED
+ * convention (`docs/extensions.md`: "If a tool makes nested LLM calls,
+ * return their combined Usage as usage"), which a well-behaved third-party
+ * "subagent"-named tool, or a future version of either package, could
+ * start following at any time. That forward-looking risk is exactly what
+ * C1 guards against — see `safeAmbiguousResultInfo`.
+ */
+export const PI_REFERENCE_PROFILE = {
+    id: "pi-reference",
+    toolNames: ["subagent"],
+    childEnvMarkers: [],
+    joinKeyConfidence: "ancestry",
+    readLaunchArgs: readAgentModeArgs,
+    readResult(result) {
+        const usage = readStandardUsage(result);
+        return { ...(usage !== undefined ? { usage } : {}) };
+    },
+};
+/**
+ * pi-subagents (npm package, tool `subagent`, action-based). Verified
+ * against the installed 0.28.0 source (`src/shared/types.ts`
+ * `getSubagentDepthEnv`): every child it spawns (foreground AND the
+ * detached background runner) carries `PI_SUBAGENT_DEPTH` — NOT
+ * `PI_SUBAGENT_PARENT_SESSION`, an earlier, unverified assumption this
+ * profile deliberately does not use. Because this marker CAN confirm a
+ * child as `role: "subagent"` (ancestry-joined, its own usage/cost already
+ * counted through that join), this profile's `readResult` deliberately
+ * never forwards `usage` even when present — forwarding it here would risk
+ * counting the same nested LLM work twice (once via the join, once via the
+ * forwarded figure). See `GENTLE_PI_PROFILE`/`PI_REFERENCE_PROFILE` for the
+ * two cases where forwarding is safe.
+ */
+export const PI_SUBAGENTS_PROFILE = {
+    id: "pi-subagents",
+    toolNames: ["subagent"],
+    childEnvMarkers: [{ name: "PI_SUBAGENT_DEPTH" }],
+    joinKeyConfidence: "ancestry",
+    readLaunchArgs(args) {
+        const agent = stringField(args, "agent");
+        const mode = stringField(args, "action");
+        return { ...(agent !== undefined ? { agent } : {}), ...(mode !== undefined ? { mode } : {}) };
+    },
+    readResult() {
+        return {};
+    },
+};
+export const BUILTIN_SUBAGENT_PROFILES = [GENTLE_PI_PROFILE, PI_REFERENCE_PROFILE, PI_SUBAGENTS_PROFILE];
+/**
+ * SUBAGENT-REQ-001/002/003: the user-configured profile built from
+ * `KANKAKU_SUBAGENT_TOOLS`/`KANKAKU_SUBAGENT_CHILD_ENV` (parsed in
+ * `config.ts`, mirroring `KANKAKU_INTERACTIVE_TOOLS`'s tolerant
+ * comma-split convention). Always additive to the built-ins, never
+ * replacing gentle-pi's own recognition. `undefined` when neither is
+ * configured, so `loadConfig` never adds an inert profile. Forwards
+ * `result.usage` generically (like `PI_REFERENCE_PROFILE`) — a documented,
+ * unavoidable residual risk: kankaku cannot know whether an arbitrary
+ * configured child process also runs kankaku itself and would otherwise be
+ * ancestry-joined, so a user who configures BOTH a child-env marker AND a
+ * tool that forwards `usage` for the same third-party package accepts that
+ * narrow double-count risk (see README "Subagents").
+ */
+export function buildConfiguredProfile(toolNames, childEnvMarkers) {
+    if (toolNames.length === 0 && childEnvMarkers.length === 0)
+        return undefined;
+    return {
+        id: "configured",
+        toolNames,
+        childEnvMarkers,
+        joinKeyConfidence: "ancestry",
+        readLaunchArgs: readAgentModeArgs,
+        readResult(result) {
+            const usage = readStandardUsage(result);
+            return { ...(usage !== undefined ? { usage } : {}) };
+        },
+    };
+}
+/** Every profile whose `toolNames` include `toolName`, in the given order. */
+export function matchToolProfiles(profiles, toolName) {
+    return profiles.filter((profile) => profile.toolNames.includes(toolName));
+}
+/**
+ * SUBAGENT-REQ-005: resolve which profile should be used to open/read a
+ * subagent span for a given tool name. Exactly one match resolves
+ * unambiguously; zero means this is not a recognised subagent tool call at
+ * all; two or more (e.g. `"subagent"`, registered by both the pi reference
+ * example and pi-subagents) is a genuine name collision — never guessed:
+ * `profile` stays `undefined` and `ambiguous` is `true` so the caller can
+ * still open a best-effort span (see `readLaunchInfo`/`readResultInfo`)
+ * without ever claiming a specific profile matched.
+ */
+/**
+ * C1 investigation note — real disambiguation was investigated and
+ * rejected for the "subagent" name collision between `PI_REFERENCE_PROFILE`
+ * and `PI_SUBAGENTS_PROFILE`, both by args/result SHAPE and by pi's own
+ * `getAllTools()[].sourceInfo.path`:
+ *
+ * - Args shape: pi-subagents' `action` field ("list"/"get"/"create"/
+ *   "update"/"delete"/"status"/"interrupt"/"resume"/"doctor" — verified
+ *   0.28.0 `src/extension/schemas.ts`) is absent from pi-reference's schema
+ *   entirely, so its PRESENCE would be conclusive — but it is only ever
+ *   set for pi-subagents' management/diagnostic calls, never for the
+ *   money-affecting single/parallel/chain execution calls (`agent`+`task`,
+ *   `tasks[]`, `chain[]`) that are the whole point of C1: those look
+ *   identical in both packages' schemas (`agent`, `task`, `tasks`,
+ *   `chain`, `cwd` all present in both). Result shape is no better: neither
+ *   package's real result carries a top-level `usage` at all (see
+ *   `PI_REFERENCE_PROFILE`'s doc comment) — no distinguishing signal is
+ *   present in exactly the calls that matter.
+ * - `sourceInfo.path`: `pi.getAllTools()` does expose which extension
+ *   registered a given tool name (`docs/extensions.md` "pi.getAllTools()").
+ *   But that same doc explicitly warns, for the structurally identical
+ *   `sourceInfo` on `pi.getCommands()`: "Use sourceInfo as the canonical
+ *   provenance field. Do not infer ownership from command names or from ad
+ *   hoc path parsing." Matching a tool's `sourceInfo.path` against a
+ *   hardcoded substring (a package name, an examples/ path) IS ad hoc path
+ *   parsing — the path is not guaranteed to contain any stable, portable
+ *   substring across install layouts (a monorepo, a symlinked/hoisted
+ *   dependency, a vendored fork). This was rejected as unreliable, not
+ *   merely inconvenient.
+ *
+ * Neither route was conclusive, so kankaku stays ambiguous by design
+ * (SUBAGENT-REQ-005: never guessed) and instead fixes the CONSEQUENCE of
+ * ambiguity — see `safeAmbiguousResultInfo`/`mergeAgreeingLaunchInfo` and
+ * `domain/work-tracker.ts#onToolEnd`.
+ */
+export function resolveToolProfile(profiles, toolName) {
+    const candidates = matchToolProfiles(profiles, toolName);
+    if (candidates.length === 1)
+        return { profile: candidates[0], ambiguous: false, candidates };
+    if (candidates.length === 0)
+        return { profile: undefined, ambiguous: false, candidates };
+    return { profile: undefined, ambiguous: true, candidates };
+}
+/** Every tool name registered by 2+ profiles at once, with the colliding profile ids — a static property of the active profile set, independent of any record. */
+export function findAmbiguousToolNames(profiles) {
+    const byTool = new Map();
+    for (const profile of profiles) {
+        for (const toolName of profile.toolNames) {
+            const ids = byTool.get(toolName) ?? [];
+            ids.push(profile.id);
+            byTool.set(toolName, ids);
+        }
+    }
+    const ambiguous = [];
+    for (const [toolName, profileIds] of byTool) {
+        if (profileIds.length > 1)
+            ambiguous.push({ toolName, profileIds });
+    }
+    return ambiguous;
+}
+/** Best-effort merge of `readLaunchArgs` across several candidate profiles (an ambiguous tool-name match): first defined field, in profile order, wins. */
+export function readLaunchInfo(candidates, args) {
+    let agent;
+    let mode;
+    for (const profile of candidates) {
+        const info = profile.readLaunchArgs(args);
+        if (agent === undefined && info.agent !== undefined)
+            agent = info.agent;
+        if (mode === undefined && info.mode !== undefined)
+            mode = info.mode;
+    }
+    return { ...(agent !== undefined ? { agent } : {}), ...(mode !== undefined ? { mode } : {}) };
+}
+/** Best-effort merge of `readResult` across several candidate profiles (an ambiguous tool-name match): first defined field, in profile order, wins — never a profile-specific field none of the candidates actually provided. */
+export function readResultInfo(candidates, result) {
+    const merged = {};
+    for (const profile of candidates) {
+        const info = profile.readResult(result);
+        if (merged.taskId === undefined && info.taskId !== undefined)
+            merged.taskId = info.taskId;
+        if (merged.agent === undefined && info.agent !== undefined)
+            merged.agent = info.agent;
+        if (merged.status === undefined && info.status !== undefined)
+            merged.status = info.status;
+        if (merged.mode === undefined && info.mode !== undefined)
+            merged.mode = info.mode;
+        if (merged.cwd === undefined && info.cwd !== undefined)
+            merged.cwd = info.cwd;
+        if (merged.usage === undefined && info.usage !== undefined)
+            merged.usage = info.usage;
+    }
+    return merged;
+}
+/**
+ * C1 (CRITICAL fix): the launch-args counterpart of `readResultInfo`'s
+ * caution, used specifically for a genuinely AMBIGUOUS tool-name match
+ * (2+ candidate profiles, none of them the winner — SUBAGENT-REQ-005).
+ * Unlike `readLaunchInfo`'s "first defined field wins" merge (kept as-is,
+ * still used for the unambiguous single-candidate case, where there is
+ * nothing to disagree about), this only keeps a field when every candidate
+ * that reports a value for it reports the SAME value — "agent/mode if they
+ * read identically, else omitted". Two candidates disagreeing (e.g. one
+ * profile reads `mode` from `args.mode`, another from `args.action`, and
+ * they differ) means kankaku genuinely does not know which is right, so
+ * the field is dropped rather than silently picking one. Never reads
+ * anything money- or join-affecting — launch args never carry `usage` or
+ * `taskId` in the first place, only descriptive `agent`/`mode`.
+ */
+export function mergeAgreeingLaunchInfo(candidates, args) {
+    let agent;
+    let agentConflict = false;
+    let mode;
+    let modeConflict = false;
+    for (const profile of candidates) {
+        const info = profile.readLaunchArgs(args);
+        if (info.agent !== undefined) {
+            if (agent === undefined)
+                agent = info.agent;
+            else if (agent !== info.agent)
+                agentConflict = true;
+        }
+        if (info.mode !== undefined) {
+            if (mode === undefined)
+                mode = info.mode;
+            else if (mode !== info.mode)
+                modeConflict = true;
+        }
+    }
+    return {
+        ...(agent !== undefined && !agentConflict ? { agent } : {}),
+        ...(mode !== undefined && !modeConflict ? { mode } : {}),
+    };
+}
+/**
+ * C1 (CRITICAL fix): the result-reading counterpart for a genuinely
+ * AMBIGUOUS tool-name match. `readResultInfo`'s own best-effort merge stays
+ * available (and is still exactly right for the UNAMBIGUOUS single-
+ * candidate case), but when 2+ profiles registered the same tool name and
+ * neither could be told apart, nothing MONEY- or JOIN-affecting is ever
+ * taken from any candidate: `usage` (would silently double-bill the day a
+ * package sharing an ambiguous tool name, e.g. "subagent", starts
+ * following pi's documented top-level `usage` convention — see
+ * `PI_REFERENCE_PROFILE`) and `taskId` (a join key) are always stripped.
+ * Purely descriptive fields (`agent`/`status`/`mode`/`cwd`) are kept from
+ * the best-effort merge — they affect neither billing nor task/child
+ * joining, only how a span/record is labelled for a human reading it.
+ * `profile` itself is never part of this shape; the caller already leaves
+ * it `undefined` for an ambiguous match (see `resolveToolProfile`).
+ */
+export function safeAmbiguousResultInfo(candidates, result) {
+    const merged = readResultInfo(candidates, result);
+    return {
+        ...(merged.agent !== undefined ? { agent: merged.agent } : {}),
+        ...(merged.status !== undefined ? { status: merged.status } : {}),
+        ...(merged.mode !== undefined ? { mode: merged.mode } : {}),
+        ...(merged.cwd !== undefined ? { cwd: merged.cwd } : {}),
+    };
+}
+/**
+ * Whether any of `markers` is present in `env`: an exact-value marker
+ * requires an exact match, a presence-only marker (`value: undefined`)
+ * matches any non-empty value. Shared by `profileMarkerMatches` (one
+ * profile's own markers) and `config.ts#detectRole` (the full active set,
+ * generalised beyond the single hardcoded `GENTLE_PI_AGENTS_CHILD` check).
+ */
+export function matchesAnyMarker(env, markers) {
+    return markers.some((marker) => {
+        const actual = env[marker.name];
+        if (actual === undefined || actual === "")
+            return false;
+        return marker.value === undefined || actual === marker.value;
+    });
+}
+/** Whether `profile`'s child-env marker(s) are present in `env`. A profile with no markers at all (e.g. `PI_REFERENCE_PROFILE`) never matches, by construction. */
+export function profileMarkerMatches(profile, env) {
+    return matchesAnyMarker(env, profile.childEnvMarkers);
+}
+/**
+ * SUBAGENT-REQ-005: resolve which profile's child-env marker(s) confirm
+ * THIS process as a subagent of a known kind — the child-side counterpart
+ * of `resolveToolProfile`. Exactly one profile's marker present resolves
+ * unambiguously; none present means this process's role, if any, must come
+ * from ancestry instead (see `config.ts#detectRole`); two or more present
+ * at once (a genuine marker collision, not expected among the built-ins) is
+ * never guessed either — `profile` stays `undefined`, but every match is
+ * still reported so `/kankaku doctor` can surface it.
+ */
+export function resolveChildProfile(profiles, env) {
+    const matchedProfiles = profiles.filter((profile) => profileMarkerMatches(profile, env));
+    return { profile: matchedProfiles.length === 1 ? matchedProfiles[0] : undefined, matchedProfiles };
+}
+/** Every distinct child-env marker declared by any of `profiles`, de-duplicated by `name` (first-declared value wins) — used to generalise `detectRole`'s single hardcoded marker check. */
+export function allChildMarkers(profiles) {
+    const byName = new Map();
+    for (const profile of profiles) {
+        for (const marker of profile.childEnvMarkers) {
+            if (!byName.has(marker.name))
+                byName.set(marker.name, marker);
+        }
+    }
+    return Array.from(byName.values());
+}
+/**
+ * C2 (CRITICAL fix): the "always confirms, regardless of interactivity"
+ * tier for `config.ts#detectRole`'s 4th param — every active profile's
+ * markers EXCEPT the single user-configured one (`id === "configured"`,
+ * built from `KANKAKU_SUBAGENT_CHILD_ENV` in `config.ts#loadConfig`). Only
+ * a real subagent runner (gentle-pi, pi-subagents) sets a built-in marker,
+ * so this tier keeps today's unconditional precedence.
+ */
+export function builtinChildMarkers(profiles) {
+    return allChildMarkers(profiles.filter((profile) => profile.id !== "configured"));
+}
+/**
+ * C2 (CRITICAL fix): the "never demotes an interactive session" tier for
+ * `config.ts#detectRole`'s 5th param — the user-configured profile's own
+ * markers only (empty when no `"configured"` profile is active). Kept
+ * separate from `builtinChildMarkers` because kankaku cannot verify an
+ * arbitrary configured environment variable name is genuinely child-only
+ * (see `config.ts#loadConfig`'s denylist and `detectRole`'s doc comment).
+ */
+export function configuredChildMarkers(profiles) {
+    return allChildMarkers(profiles.filter((profile) => profile.id === "configured"));
+}

package/dist/domain/sync-plan.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Decide which tasks a sync run should push, without touching the network
+ * or the filesystem. Pure, no I/O — see `sync-runner.ts` for the adapter
+ * that drives this with a real clock, `WorkLog` and `WorkSink`.
+ *
+ * A task is not final the moment it is first written: a background
+ * subagent can settle after its orchestrator and extend the task's union
+ * (see `task-view.ts`), which is exactly why every sync also revisits a
+ * trailing window behind the watermark instead of only pushing brand-new
+ * tasks (proposal §6.0).
+ */
+import type { TaskView } from "./task-view.ts";
+/** Persisted sync state (`<KANKAKU_DIR>/sync-state.json`). */
+export interface SyncState {
+    /** High-watermark ISO timestamp: everything with `endedAt` at or before `syncedThrough - window` is considered done. `undefined` before the first successful sync. */
+    syncedThrough?: string;
+    /** Content hash per task id (see {@link computeTaskContentHash}), kept for as long as the task exists — never pruned by the revisit window (see {@link pruneHashes}). */
+    hashes: Record<string, string>;
+    /** The hub URL this state was synced against; a state written for a different URL is treated as absent (full sync). */
+    target: string;
+    /** Set after a network/5xx failure stopped a run short; cleared by the next fully-successful run. */
+    lastError?: {
+        message: string;
+        at: string;
+    };
+    /**
+     * The `WorkLog`'s cheap change signal (`version()`) as of the last real
+     * (non-short-circuited) automatic-or-manual sync attempt. The automatic
+     * path (`session_start`/`agent_settled`) compares this against the
+     * current value to skip entirely — no `readAll()`, no network — when
+     * nothing has changed and the last attempt did not error. See
+     * `adapters/sync-runner.ts#runSync`.
+     */
+    logVersion?: string | number;
+    /**
+     * `Clock`-based timestamp (ms) of the last real (non-short-circuited)
+     * automatic sync attempt, persisted so the automatic path's throttle
+     * (`KANKAKU_SYNC_MIN_INTERVAL_MINUTES`) holds across processes, not just
+     * within one. Written by every run that reaches the sink, manual or
+     * automatic; only the automatic path READS it to throttle itself.
+     */
+    lastRunAt?: number;
+}
+export interface SyncPlanOptions {
+    /** The configured hub URL. A state whose `target` differs triggers a full sync. */
+    target: string;
+    /** Revisit window in hours, applied behind `syncedThrough`. Defaults to 24. */
+    windowHours?: number;
+    /** Force every task to be (re-)evaluated, e.g. `/kankaku sync all`. */
+    full?: boolean;
+}
+export interface SyncPlan {
+    /** Tasks whose content changed (or were never synced) and therefore need a request: new work in the window oldest-first, then corrections to rows the hub already holds, newest-first (see {@link planSync}). */
+    toSync: TaskView[];
+    /** How many eligible tasks were skipped because their stored hash already matched — no request needed for them. */
+    unchangedCount: number;
+    /** `true` when this run evaluated every task rather than only the revisit window. */
+    isFullSync: boolean;
+    /**
+     * Tasks outside this run's revisit window that were NEVER synced to this
+     * hub: an ordinary incremental sync does not look that far back for new
+     * work, so only `sync all` (or `backfill`) uploads them. A task the hub
+     * already holds never appears here — if it changed it is in `toSync`.
+     * Always empty for a full sync. Surfaced by `/kankaku sync status`.
+     */
+    staleOutsideWindow: TaskView[];
+    /** Already-synced rows that changed but were left for a later run by {@link MAX_CORRECTIONS_PER_RUN}. */
+    correctionsDeferred: number;
+}
+/** How many already-synced, out-of-window rows one incremental run corrects at most; the rest wait for the next run (or `sync all`). */
+export declare const MAX_CORRECTIONS_PER_RUN = 50;
+/**
+ * Content hash of everything a re-sync could change: the measurement
+ * fields (never the assignment — a reassignment made in the web is never
+ * visible locally, and must never trigger a resync on its own). A task
+ * whose hash matches the last stored one is unchanged and can be skipped
+ * without a request. Includes the derived measurement-quality fields
+ * (`domain/hub-entry.ts`) too, not just the raw numbers they are computed
+ * from: a background subagent that joins *after* this task was first
+ * synced can turn `cost_quality`/`subagent_linkage` from `"unknown"`/
+ * `"unlinked"` into a better answer without any of the other numeric
+ * fields necessarily changing (e.g. a joined child with no cost of its own
+ * still flips `subagent_linkage`) — that must still trigger a resync.
+ * `waiting_quality` is a true constant (`domain/hub-entry.ts`'s
+ * `computeWaitingQuality`) and is deliberately left out: it can never
+ * change between two evaluations of the same task. `sessionDir` is also a
+ * measurement-style field (`domain/hub-entry.ts`'s `session_dir`, sent on
+ * both create and update) — its own change, e.g. a resume that switches to
+ * a non-default session directory, must trigger a resync on its own even
+ * when nothing else changed.
+ */
+export declare function computeTaskContentHash(task: TaskView): string;
+/**
+ * Decide which tasks need a request this run.
+ *
+ * Eligibility: every task, when there is no state yet, the state's
+ * `target` differs from the configured hub URL, or `options.full` is set
+ * (a full sync); otherwise only tasks with `endedAt` after
+ * `syncedThrough - window`. Within the eligible set, a task is only
+ * included in `toSync` when its current content hash differs from the one
+ * stored in `state.hashes` (absent, i.e. never synced, always counts as
+ * different).
+ */
+export declare function planSync(tasks: TaskView[], state: SyncState | undefined, options: SyncPlanOptions): SyncPlan;
+/**
+ * Drop hash entries for task ids that no longer exist in `tasks` (which
+ * should not normally happen since `worklog.jsonl` is append-only — this
+ * is a defensive backstop, not the normal path). `sync-state.json`'s
+ * `hashes` are otherwise kept **forever** for every task this process
+ * still knows about, regardless of how far outside the revisit window its
+ * `endedAt` has fallen (G2 fix).
+ *
+ * This used to also drop a hash once its task's `endedAt` fell behind
+ * `syncedThrough - window` — but `planSync`'s `staleOutsideWindow` treats a
+ * *missing* hash exactly like "content changed" (there is no third state
+ * for "unchanged but I forgot"), so that window-based pruning made every
+ * task older than the window look permanently changed, forever, the moment
+ * its hash was first pruned: `/kankaku sync status` would report a
+ * never-shrinking "changed outside the window" count that trained users
+ * to ignore it (the bug this rewrite fixes).
+ *
+ * Never pruning by window instead means `hashes` grows with the total
+ * number of distinct tasks a directory has ever synced, not with time — an
+ * FNV-1a hash is 8 hex chars and a task id (a `crypto.randomUUID()`) is 36,
+ * so each retained entry costs roughly 50 bytes of JSON. Measured: 10,000
+ * entries serialize to well under 1MB (see `tests/sync-plan.test.ts`'s
+ * state-size-bound test) — even a directory with a decade of daily,
+ * multi-task-per-day history stays a small, instantly-parseable file. A
+ * coarser design (e.g. one rolling digest per closed day) would bound the
+ * file even tighter, but cannot answer "which specific task changed" —
+ * `staleOutsideWindow` needs exactly that, per-task precision, to stay
+ * useful — so it was rejected in favour of this simpler, still-cheap
+ * per-task scheme.
+ *
+ * No migration is needed for an existing `sync-state.json`: it already has
+ * exactly this shape (`Record<taskId, hash>`), just with some outside-
+ * window entries already missing from a build that pruned them. The first
+ * sync after upgrading treats each of those exactly like "never synced" —
+ * a real fact this process cannot know is false, since the old hash is
+ * genuinely gone — and reports it once via `staleOutsideWindow`; once that
+ * task's hash is recorded again (an ordinary `sync all`, or simply being
+ * observed unchanged), this function never drops it again. See
+ * `tests/sync-plan.test.ts`'s "first sync after upgrading" test.
+ *
+ * Accumulated in a `Map` and emitted via `Object.fromEntries` (never
+ * `pruned[id] = ...` on a plain object), since a task id ultimately traces
+ * back to free-text worklog content: a value like `__proto__` written to a
+ * plain object would silently no-op (the inherited accessor ignores a
+ * non-object assignment) instead of being kept as an own property.
+ */
+export declare function pruneHashes(hashes: Record<string, string>, tasks: TaskView[]): Record<string, string>;