@knpkv/jira-clockify 1.3.0 → 1.4.1

package/dist/src/agent/sessions.js

@@ -0,0 +1,868 @@
+import { Data } from "effect";
+import { scheduleRuns } from "./schedule.js";
+import * as SourceConsumption from "./sourceConsumption.js";
+/**
+ * Pure core for turning Agent Session evidence into Proposed Worklogs.
+ *
+ * **Mental model**
+ *
+ * - **Evidence, not a side**: a transcript records that work happened at particular moments,
+ *   never how long it lasted. Everything here derives a *proposal*; nothing here is
+ *   authoritative and nothing here writes. See ADR-0006.
+ * - **Last-touch partition**: every instant between two adjacent Session Activity events is
+ *   credited to the *earlier* event's session, and only if the gap is within the Idle Cap.
+ *   Each interval is therefore credited exactly once, so the sum over all Issue Keys can never
+ *   exceed the wall clock of the window. That inequality is the safety property that makes a
+ *   Proposed Worklog safe to accept without auditing the rest of the day.
+ * - **Attribution precedence**: branch, then path, then Standing Attribution, then Coding Agent.
+ *   The first signal to yield an Issue Key wins, so re-running never reshuffles attributions.
+ * - **Closed choice set**: a Coding Agent may only pick an Issue Key that literally appears in
+ *   the transcript. {@link attributeSession} enforces that structurally, so an invented key is
+ *   impossible rather than merely discouraged.
+ *
+ * **Gotchas**
+ *
+ * - Provider-agnostic on purpose: nothing here knows about Claude, JSONL, or the filesystem, so
+ *   adding a second Coding Agent is additive.
+ * - Placeholder rejection applies to *mined* candidates only, never to a branch or path. A branch
+ *   name is a deliberate act; a number in prose is not. A real project numbered `PROJ-123` would
+ *   otherwise be unattributable.
+ * - Credit is bounded to the window by the caller: only Session Activity inside `[from, to)` is
+ *   passed in, so the last event of the window contributes no trailing interval. That is a
+ *   deliberate under-count of at most one Idle Cap per window edge.
+ *
+ * @module
+ */
+import { localDay, nextLocalMidnight } from "../utils/time.js";
+/**
+ * Attribution Signals in precedence order — the first to yield an Issue Key wins. Also the
+ * trust order: a bucket built from several sessions reports its *weakest* signal, because a row
+ * is only as trustworthy as its least trustworthy evidence.
+ */
+export const ATTRIBUTION_PRECEDENCE = [
+    "branch",
+    "path",
+    "standing",
+    "agent",
+    "none"
+];
+const signalRank = (signal) => {
+    const index = ATTRIBUTION_PRECEDENCE.indexOf(signal);
+    return index === -1 ? ATTRIBUTION_PRECEDENCE.length : index;
+};
+/**
+ * An Issue Key as Jira writes them: at least two leading uppercase alphanumerics then a number.
+ * Deliberately stricter than the Clockify description parser — this runs over free prose and
+ * directory names, where `feat/jcf-ai` and `v2-3` must not look like tickets.
+ *
+ * Bounded by explicit non-alphanumerics rather than `\b`, because `_` is a word character: `\b` put
+ * no boundary between `_` and `P`, so the branch and worktree names people actually use —
+ * `feature_PROJ-42_work` — matched nothing at all, and the session went unattributed and therefore
+ * unlogged. Underscore is the only difference; letters and digits still have to stop.
+ */
+const TICKET_KEY = /(?<![A-Za-z0-9])[A-Z][A-Z0-9]{1,9}-\d{1,6}(?![A-Za-z0-9])/g;
+const matchTicketKeys = (text) => [...text.matchAll(TICKET_KEY)].map((m) => m[0]);
+/**
+ * True when a string is an Issue Key and nothing else.
+ *
+ * A Standing Attribution is the one Issue Key nobody mines — it is typed into a config file — so it
+ * is also the one that can be empty or malformed. An empty key writes a Clockify description of
+ * `[] …`, which {@link parseTicketKey} then refuses to read back, so the next tally cannot see the
+ * entry and a watch writes the same time again on every settled tick, forever.
+ */
+export const isTicketKey = (value) => {
+    const matches = matchTicketKeys(value);
+    return matches.length === 1 && matches[0] === value;
+};
+/**
+ * True for Issue Keys whose number reads as documentation filler rather than a real ticket:
+ * an ascending run from 1 (`123`, `1234`) or a repeated digit (`333`, `4444`), both at least
+ * three digits long. Short numbers are left alone so a young project's `PROJ-12` still counts.
+ *
+ * Only ever applied to keys mined from prose. `PROJ-XXXX` needs no rule — it has no digits and
+ * so never matches {@link TICKET_KEY} in the first place.
+ */
+export const isPlaceholderTicketKey = (key) => {
+    const digits = key.slice(key.lastIndexOf("-") + 1);
+    if (digits.length < 3)
+        return false;
+    const ascendingFromOne = digits.split("").every((d, i) => d === String((i + 1) % 10));
+    const allSameDigit = digits.split("").every((d) => d === digits[0]);
+    return ascendingFromOne || allSameDigit;
+};
+const DEFAULT_CANDIDATE_LIMIT = 20;
+/**
+ * Issue Keys mentioned anywhere in a transcript, deduped and in order of first appearance,
+ * with placeholders dropped and the list capped so a Coding Agent prompt stays bounded.
+ *
+ * Deliberately *unordered by frequency*: a known-issues document mentions the tickets it
+ * describes dozens of times, so frequency is anti-correlated with what should be billed.
+ */
+export const mineTicketKeys = (text, options) => {
+    const limit = options?.limit ?? DEFAULT_CANDIDATE_LIMIT;
+    const seen = new Set();
+    const keys = [];
+    for (const key of matchTicketKeys(text)) {
+        if (seen.has(key) || isPlaceholderTicketKey(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+        if (keys.length >= limit)
+            break;
+    }
+    return keys;
+};
+/**
+ * The Issue Key a git branch names, or null. Takes the first match so `PROJ-1/PROJ-2` resolves
+ * predictably, and applies no placeholder filter — naming a branch is a deliberate act.
+ */
+export const ticketKeyFromBranch = (branch) => {
+    if (branch === null || branch === undefined || branch === "")
+        return null;
+    return matchTicketKeys(branch)[0] ?? null;
+};
+/**
+ * The Issue Key a working directory path names, or null. Takes the *last* match so the deepest
+ * segment wins — a worktree at `~/dev/repo/worktrees/PROJ-1/PROJ-2` is working on `PROJ-2`.
+ *
+ * This is what makes detached worktrees (whose branch reads `HEAD`) attributable.
+ */
+export const ticketKeyFromPath = (cwd) => {
+    const keys = matchTicketKeys(cwd);
+    return keys.length > 0 ? keys[keys.length - 1] : null;
+};
+const withoutTrailingSlash = (path) => path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+/** Expand a leading `~` against `home`. Paths without one are returned unchanged. */
+export const expandHomePath = (path, home) => {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return `${withoutTrailingSlash(home)}/${path.slice(2)}`;
+    if (path.startsWith("~\\"))
+        return `${home.replace(/[\\/]+$/, "")}\\${path.slice(2)}`;
+    return path;
+};
+const windowsAbsolute = (value) => /^[A-Za-z]:[\\/]/.test(value) || /^[\\/]{2}[^\\/]+[\\/][^\\/]+/.test(value);
+/**
+ * True when `path` is `prefix` or sits beneath it. Compares on a path *separator boundary*, so
+ * `/a/bc` is not inside `/a/b` — the bug a bare `startsWith` would introduce.
+ */
+export const isWithinPrefix = (path, prefix) => {
+    const windows = windowsAbsolute(path);
+    if (windows !== windowsAbsolute(prefix))
+        return false;
+    const normalise = (value) => windows
+        ? value.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase()
+        : withoutTrailingSlash(value);
+    const normalisedPath = normalise(path);
+    const normalisedPrefix = normalise(prefix);
+    if (normalisedPrefix.length === 0)
+        return false;
+    return normalisedPath === normalisedPrefix || normalisedPath.startsWith(`${normalisedPrefix}/`);
+};
+/**
+ * True when a session's working directory sits inside any Session Root. Sessions outside every
+ * root are never read, so scratch directories and side projects cannot generate proposals.
+ */
+export const isWithinSessionRoots = (cwd, roots) => roots.some((root) => isWithinPrefix(cwd, root));
+/**
+ * The Standing Attribution for a working directory: the Issue Key mapped to the *longest*
+ * matching directory prefix, so `~/dev/docs/releases` and `~/dev/docs/interviews` can differ.
+ */
+export const standingAttribution = (cwd, map) => {
+    let best = null;
+    let bestLength = -1;
+    for (const [prefix, ticketKey] of Object.entries(map)) {
+        if (!isWithinPrefix(cwd, prefix) || prefix.length <= bestLength)
+            continue;
+        best = ticketKey;
+        bestLength = prefix.length;
+    }
+    return best;
+};
+/**
+ * Place a session using the deterministic signals only, or null when none apply.
+ *
+ * Kept separate from {@link attributeSession} because the *absence* of a result here is exactly
+ * the condition for spending a Coding Agent call — which is why a run where every session is
+ * branch-attributed costs nothing.
+ */
+export const deterministicAttribution = (session, options) => {
+    const fromBranch = ticketKeyFromBranch(session.gitBranch);
+    if (fromBranch !== null)
+        return { ticketKey: fromBranch, signal: "branch" };
+    const fromPath = ticketKeyFromPath(session.cwd);
+    if (fromPath !== null)
+        return { ticketKey: fromPath, signal: "path" };
+    const standing = standingAttribution(session.cwd, options.standingMap);
+    if (standing !== null)
+        return { ticketKey: standing, signal: "standing" };
+    return null;
+};
+/**
+ * Resolve one session's final attribution, applying the full precedence and both guards on a
+ * Coding Agent's answer: the chosen key must appear in the session's own candidate set, and a
+ * choice below `confidenceFloor` is marked so it can be reported without being offered.
+ */
+export const attributeSession = (session, options) => {
+    const deterministic = deterministicAttribution(session, { standingMap: options.standingMap });
+    if (deterministic !== null) {
+        return {
+            sessionId: session.sessionId,
+            ticketKey: deterministic.ticketKey,
+            signal: deterministic.signal,
+            confidence: null,
+            belowConfidenceFloor: false
+        };
+    }
+    const choice = options.agentChoice;
+    const unattributed = {
+        sessionId: session.sessionId,
+        ticketKey: null,
+        signal: "none",
+        confidence: null,
+        belowConfidenceFloor: false
+    };
+    // The choice set is closed over the transcript's own text: a key the transcript never
+    // mentioned cannot reach a worklog, however confidently it was named.
+    if (choice === null || choice === undefined || !session.candidateKeys.includes(choice.ticketKey)) {
+        return unattributed;
+    }
+    return {
+        sessionId: session.sessionId,
+        ticketKey: choice.ticketKey,
+        signal: "agent",
+        confidence: choice.confidence,
+        belowConfidenceFloor: choice.confidence < options.confidenceFloor
+    };
+};
+/**
+ * Merge spans that touch or overlap, so a hundred one-minute credits read as one block of work.
+ */
+export const mergeSpans = (spans) => {
+    const sorted = [...spans].sort((a, b) => a.startMs - b.startMs || a.endMs - b.endMs);
+    const merged = [];
+    for (const span of sorted) {
+        const last = merged[merged.length - 1];
+        if (last !== undefined && span.startMs <= last.endMs) {
+            last.endMs = Math.max(last.endMs, span.endMs);
+            continue;
+        }
+        merged.push({ startMs: span.startMs, endMs: span.endMs });
+    }
+    return merged;
+};
+/**
+ * Merge overlapping spans, then cut the result at every local midnight.
+ *
+ * Merging alone is not enough anywhere spans are day-bucketed afterwards: two windows that meet at
+ * midnight touch, so a plain merge welds them into one span whose start decides the day — putting a
+ * whole morning's work onto the previous day. Every merge in this module goes through here.
+ */
+export const mergeSpansWithinDays = (spans) => {
+    const bounded = [];
+    for (const span of mergeSpans(spans)) {
+        let cursor = span.startMs;
+        while (cursor < span.endMs) {
+            const chunkEnd = Math.min(span.endMs, nextLocalMidnight(cursor));
+            bounded.push({ startMs: cursor, endMs: chunkEnd });
+            cursor = chunkEnd;
+        }
+    }
+    return bounded;
+};
+/**
+ * The windows a single session was active in: each gap between its own adjacent events, cut off at
+ * the Idle Cap, and split at local midnight. Merged, so contiguous work reads as one block.
+ */
+const sessionActiveWindows = (events, capMs, observedAtMs) => {
+    const raw = [];
+    const sorted = [...events].sort((a, b) => a - b);
+    for (let index = 0; index < sorted.length - 1; index++) {
+        const from = sorted[index];
+        const next = sorted[index + 1];
+        if (from === undefined || next === undefined)
+            continue;
+        // Beyond the Idle Cap nobody was working, so the window ends there rather than at the next event.
+        raw.push({ startMs: from, endMs: Math.min(next, from + capMs) });
+    }
+    // The last prompt gets its window too, bounded by the Idle Cap and by how far we can see.
+    //
+    // Not cosmetic. Without it a final prompt contributes nothing *until* some later prompt arrives,
+    // and then a window appears retroactively — one that can overlap a block already settled and
+    // written, halving that block's share after the fact while the new share is written as well. Two
+    // tickets then hold more time between them than the clock has. Materialising it on sight is what
+    // makes "settled" mean settled: every window a prompt will ever produce exists as soon as the
+    // prompt does.
+    const last = sorted[sorted.length - 1];
+    if (last !== undefined && observedAtMs > last) {
+        raw.push({ startMs: last, endMs: Math.min(observedAtMs, last + capMs) });
+    }
+    return mergeSpansWithinDays(raw);
+};
+/**
+ * When each session was working: the gaps between its own adjacent events, cut off at the Idle Cap.
+ *
+ * Deliberately stops short of dividing anything. Sharing has to happen between *Issue Keys*, and
+ * which key a session belongs to is not known until it has been attributed — two sessions on the
+ * same ticket must not halve each other's time. See {@link splitCredits}.
+ */
+export const activeWindows = (activity, options) => {
+    const capMs = Math.max(0, options.idleCapSeconds) * 1000;
+    const eventsBySession = new Map();
+    for (const event of activity) {
+        const events = eventsBySession.get(event.sessionId) ?? [];
+        events.push(event.atMs);
+        eventsBySession.set(event.sessionId, events);
+    }
+    return [...eventsBySession.entries()]
+        .map(([sessionId, events]) => ({
+        sessionId,
+        spans: sessionActiveWindows(events, capMs, Math.min(options.observedAtMs, options.boundsBySession?.get(sessionId) ?? Number.POSITIVE_INFINITY))
+    }))
+        .filter((session) => session.spans.length > 0)
+        .sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+};
+/**
+ * Every instant where at least one bucket was active, cut into slices at each point where the set
+ * of active buckets changes, with the buckets active in that slice.
+ */
+const overlapSlices = (spansByBucket) => {
+    const boundaries = new Set();
+    for (const spans of spansByBucket.values()) {
+        for (const span of spans) {
+            boundaries.add(span.startMs);
+            boundaries.add(span.endMs);
+        }
+    }
+    const ordered = [...boundaries].sort((a, b) => a - b);
+    const slices = [];
+    for (let i = 0; i < ordered.length - 1; i++) {
+        const startMs = ordered[i];
+        const endMs = ordered[i + 1];
+        const bucketIds = [...spansByBucket.entries()]
+            .filter(([, spans]) => spans.some((span) => span.startMs <= startMs && span.endMs >= endMs))
+            .map(([bucketId]) => bucketId);
+        if (bucketIds.length > 0)
+            slices.push({ startMs, endMs, bucketIds });
+    }
+    return slices;
+};
+/**
+ * The shortest stretch that may own time on its own, in seconds.
+ *
+ * Fifteen minutes, because a timeline that changes ticket every three minutes is not a record of how
+ * anyone works — it is an artefact of reading several concurrent transcripts at once. A day of that
+ * is unreadable on a calendar and indefensible on a timesheet.
+ */
+export const DEFAULT_DWELL_SECONDS = 900;
+const sameOwners = (a, b) => a.length === b.length && a.every((id, index) => id === b[index]);
+/**
+ * True when two touching stretches may become one: same owners, same local day.
+ *
+ * The day check is load-bearing. Runs are bucketed by the day their start falls in, so welding a
+ * stretch ending at midnight to the one beginning there would move the small hours of Tuesday onto
+ * Monday and report Tuesday as empty. The windows arrive already split at midnight for exactly this
+ * reason; coalescing must not undo it.
+ */
+const joinable = (previous, next) => previous.endMs === next.startMs &&
+    sameOwners(previous.bucketIds, next.bucketIds) &&
+    localDay(new Date(previous.startMs)) === localDay(new Date(next.startMs));
+/** Join touching stretches with identical owners. A gap of idle time always separates two runs. */
+const mergeRuns = (runs) => {
+    const merged = [];
+    for (const run of runs) {
+        const previous = merged[merged.length - 1];
+        if (previous !== undefined && joinable(previous, run)) {
+            merged[merged.length - 1] = { ...previous, endMs: run.endMs };
+            continue;
+        }
+        merged.push(run);
+    }
+    return merged;
+};
+/**
+ * Coalesce ownership so it changes no more often than the Dwell Floor.
+ *
+ * **What this is for.** Three concurrent sessions on three Issue Keys interleave their prompts, and
+ * read literally that says the work changed ticket every few minutes. It did not — that is an
+ * artefact of reading several transcripts at once. A day of it is two dozen slivers on a calendar and
+ * indefensible on a timesheet.
+ *
+ * **Two rules, in order.**
+ *
+ * 1. *A ticket present for less than the floor inside one connected source cluster, interrupting work
+ *    that resumes after it, was not a ticket that was worked on.* It was a keystroke inside other work — a branch
+ *    checked, a file opened, a question asked — so its time goes to the work around it. This is what
+ *    actually removes the slivers: they rarely touch anything, because a transcript goes quiet
+ *    between prompts, and they are as often overlapping as adjacent, because concurrent sessions
+ *    overlap by definition. Adjacency and overlap were both tried as the test and both left the
+ *    interleaving as they found it. The requirement for work on *both* sides is what keeps a genuine
+ *    short piece of work — eight minutes on another ticket, and then the day moves on — from being
+ *    swallowed by what came before it.
+ * 2. *Tenancy, not adjacency.* Between tickets that were genuinely worked on, whoever takes the
+ *    timeline holds it for at least the floor: a stretch beginning inside that tenure and owned by
+ *    someone else is credited to the incumbent. This catches two real tickets alternating quickly.
+ *
+ * **What it never does.** It reassigns time and never creates or drops any — idle gaps are not swept
+ * into a tenure — so the inequality that makes a proposal safe to accept survives intact. Nothing is
+ * ever welded across a local midnight, because runs are bucketed by the day they start in.
+ *
+ * **Unplaced hours take no part.** A stretch nothing placed neither holds a tenure nor loses its time
+ * to one: promoting it would bill work no transcript placed on that ticket, and demoting an
+ * attributed sliver into it would quietly discard billable work. An attributed tenure simply
+ * continues across it.
+ *
+ * **A minor ticket with nothing to belong to keeps its own time.** Four minutes alone in an otherwise
+ * empty day has no surrounding work to join, and dropping it would lose work that happened.
+ */
+export const applyDwellFloor = (slices, options) => {
+    const dwellMs = Math.max(0, options.dwellSeconds) * 1000;
+    if (dwellMs === 0)
+        return mergeRuns(slices);
+    const runs = mergeRuns(slices);
+    // How long each attributed ticket was present in one connected source cluster, sharing ignored:
+    // the question is whether it was worked on at all, not how much of a shared minute it would be
+    // credited. A later disconnected cluster must not change ownership a watch already settled.
+    const clusterIds = [];
+    let clusterId = 0;
+    for (let index = 0; index < runs.length; index++) {
+        const run = runs[index];
+        const previous = runs[index - 1];
+        if (previous !== undefined &&
+            (previous.endMs !== run.startMs || localDay(new Date(previous.startMs)) !== localDay(new Date(run.startMs)))) {
+            clusterId++;
+        }
+        clusterIds.push(clusterId);
+    }
+    const presence = new Map();
+    const presenceKey = (bucketId, cluster) => `${bucketId}\u0000${String(cluster)}`;
+    for (let index = 0; index < runs.length; index++) {
+        const run = runs[index];
+        const cluster = clusterIds[index];
+        for (const bucketId of run.bucketIds) {
+            const key = presenceKey(bucketId, cluster);
+            presence.set(key, (presence.get(key) ?? 0) + (run.endMs - run.startMs));
+        }
+    }
+    const major = (bucketId, index) => !options.attributed(bucketId) || (presence.get(presenceKey(bucketId, clusterIds[index])) ?? 0) >= dwellMs;
+    /** The nearest major, attributed owners on the same day, looking one way from `index`. */
+    const majorOwnersToward = (index, day, step) => {
+        let boundary = step === -1 ? runs[index].startMs : runs[index].endMs;
+        for (let at = index + step; at >= 0 && at < runs.length; at += step) {
+            const candidate = runs[at];
+            if (localDay(new Date(candidate.startMs)) !== day)
+                return undefined;
+            // A settled idle gap is a temporal barrier: work appended beyond it must never reassign a
+            // block a watch could already have written. Only a connected source cluster may absorb a
+            // minor interruption.
+            if (step === -1 ? candidate.endMs !== boundary : candidate.startMs !== boundary)
+                return undefined;
+            boundary = step === -1 ? candidate.startMs : candidate.endMs;
+            const owners = candidate.bucketIds.filter((id) => major(id, at) && options.attributed(id));
+            if (owners.length > 0)
+                return owners;
+        }
+        return undefined;
+    };
+    const withoutMinors = runs.map((run, index) => {
+        const day = localDay(new Date(run.startMs));
+        const kept = run.bucketIds.filter((id) => major(id, index));
+        if (kept.length > 0)
+            return { ...run, bucketIds: kept };
+        // Every owner was minor, so this is only an *interruption* if the work it interrupts resumes:
+        // there has to be major work on both sides of it. Eight minutes on another ticket after half an
+        // hour, with nothing after it, is a short piece of work rather than a keystroke inside a longer
+        // one — and swallowing it would lose the change of ticket a person actually made.
+        const before = majorOwnersToward(index, day, -1);
+        const after = majorOwnersToward(index, day, 1);
+        return before === undefined || after === undefined ? run : { ...run, bucketIds: before };
+    });
+    // Phase two: between tickets that were genuinely worked on, ownership holds for the floor.
+    let tenant = null;
+    const held = [];
+    for (const run of mergeRuns(withoutMinors)) {
+        const previous = held[held.length - 1];
+        if (previous !== undefined &&
+            (previous.endMs !== run.startMs || localDay(new Date(previous.startMs)) !== localDay(new Date(run.startMs)))) {
+            tenant = null;
+        }
+        const attributedRun = run.bucketIds.every(options.attributed);
+        if (!attributedRun) {
+            held.push(run);
+            continue;
+        }
+        const sameDay = tenant !== null && localDay(new Date(tenant.sinceMs)) === localDay(new Date(run.startMs));
+        if (tenant !== null && sameDay && sameOwners(tenant.bucketIds, run.bucketIds)) {
+            held.push(run);
+            continue;
+        }
+        const overlapsTenant = tenant !== null && run.bucketIds.some((id) => tenant.bucketIds.includes(id));
+        if (tenant !== null && sameDay && run.startMs - tenant.sinceMs < dwellMs && !overlapsTenant) {
+            held.push({ ...run, bucketIds: tenant.bucketIds });
+            continue;
+        }
+        tenant = { bucketIds: run.bucketIds, sinceMs: run.startMs };
+        held.push(run);
+    }
+    return mergeRuns(held);
+};
+/**
+ * Coalesce a bucket's runs into the blocks a person sees, adding up the credit each one carries.
+ *
+ * `gapMs` is the Dwell Floor. Once ownership cannot change inside the floor, two runs of the same
+ * ticket four minutes apart are one stretch of work with a pause in it, and offering them as two
+ * blocks says something about the day that is not true. Runs that merely touch are joined at any
+ * floor, including zero.
+ *
+ * Never across a local midnight, because everything downstream buckets by day: welding the last run
+ * of Monday to the first of Tuesday would file a whole morning under the wrong date.
+ */
+const coalesceBlocks = (spans, gapMs) => {
+    const ordered = [...spans].sort((a, b) => a.startMs - b.startMs);
+    const joined = [];
+    for (const span of ordered) {
+        const previous = joined[joined.length - 1];
+        if (previous !== undefined &&
+            span.startMs - previous.endMs <= gapMs &&
+            localDay(new Date(previous.startMs)) === localDay(new Date(span.startMs))) {
+            joined[joined.length - 1] = {
+                creditedMs: previous.creditedMs + span.creditedMs,
+                endMs: Math.max(previous.endMs, span.endMs),
+                startMs: previous.startMs,
+                sourceStartMs: Math.min(previous.sourceStartMs, span.sourceStartMs)
+            };
+            continue;
+        }
+        joined.push(span);
+    }
+    return joined;
+};
+/**
+ * Give every block whole seconds that add up to the day's total, exactly.
+ *
+ * Flooring each block on its own leaves the row short by up to a second per block, and a row whose
+ * blocks do not add up to it is a row nobody can check — the panel would offer 56m 36s and its five
+ * blocks would come to 56m 32s. The seconds the flooring drops go to the blocks with the largest
+ * fractional part, which is the same rule an invoice uses to make its lines sum to its total.
+ */
+const wholeSeconds = (spans, totalSeconds) => {
+    const floored = spans.map((span) => ({
+        remainder: (span.creditedMs / 1000) - Math.floor(span.creditedMs / 1000),
+        seconds: Math.floor(span.creditedMs / 1000),
+        span
+    }));
+    let spare = totalSeconds - floored.reduce((sum, entry) => sum + entry.seconds, 0);
+    // Largest fractional part first, and an earlier block wins a tie so the result never depends on
+    // the order runs happened to arrive in.
+    const order = [...floored].sort((a, b) => b.remainder - a.remainder || a.span.startMs - b.span.startMs);
+    for (const entry of order) {
+        if (spare <= 0)
+            break;
+        entry.seconds += 1;
+        spare -= 1;
+    }
+    const nextIndex = new Map();
+    return floored.map((entry) => {
+        const allocationIndex = nextIndex.get(entry.span.sourceStartMs) ?? 0;
+        nextIndex.set(entry.span.sourceStartMs, allocationIndex + 1);
+        return {
+            allocationIndex,
+            endMs: entry.span.endMs,
+            seconds: entry.seconds,
+            startMs: entry.span.startMs,
+            sourceStartMs: entry.span.sourceStartMs
+        };
+    });
+};
+/**
+ * Share time between buckets, scheduling overlapping attributed work into sequential blocks.
+ *
+ * Where several buckets were active at the same instant, that instant is divided equally between
+ * them, so an hour spent on three tickets at once credits twenty minutes to each rather than an
+ * hour to whichever session happened to log an event first. Two sessions on the *same* bucket do
+ * not divide anything — their windows are unioned first, because there is no ambiguity about which
+ * Issue Key that time belongs to.
+ *
+ * A slice's duration is divided, never duplicated, so the total across every bucket can never
+ * exceed the wall clock of the day. With a positive dwell floor, overlapping attributed runs
+ * are scheduled evenly among the strongest tickets that fit; zero preserves raw shares.
+ */
+const shareBetweenBuckets = (spansByBucket, options) => {
+    const totals = new Map();
+    const add = (bucketId, day, creditedMs, activeMs) => {
+        const byDay = totals.get(bucketId) ?? new Map();
+        const existing = byDay.get(day) ?? { creditedMs: 0, activeMs: 0 };
+        byDay.set(day, { creditedMs: existing.creditedMs + creditedMs, activeMs: existing.activeMs + activeMs });
+        totals.set(bucketId, byDay);
+    };
+    // Ownership is coalesced first, so the hours and the picture come from the same timeline. Deriving
+    // the totals from the runs and the spans from the original windows would put a row's seconds and
+    // its blocks at odds — and the blocks are what a person checks the seconds against.
+    const originalRuns = applyDwellFloor(overlapSlices(spansByBucket).map((run) => ({
+        ...run,
+        bucketIds: run.bucketIds.filter((id) => !options.coveredByCertain(id, run.bucketIds))
+    })), options);
+    const runs = scheduleRuns(originalRuns, options.dwellSeconds, options.attributed);
+    for (const run of originalRuns) {
+        for (const id of run.bucketIds)
+            add(id, localDay(new Date(run.startMs)), 0, run.endMs - run.startMs);
+    }
+    const runSpans = new Map();
+    const settlementEnds = new Map();
+    const sourceStarts = new Map();
+    for (const run of runs) {
+        // Windows are already day-bounded, so a run never straddles two days.
+        const day = localDay(new Date(run.startMs));
+        const duration = run.endMs - run.startMs;
+        // Divided, never duplicated: this is the one place an instant becomes seconds, and it is the
+        // same number that reaches the row's total and the block a person accepts.
+        const creditedMs = duration / run.bucketIds.length;
+        for (const [index, bucketId] of run.bucketIds.entries()) {
+            add(bucketId, day, creditedMs, 0);
+            const byDay = settlementEnds.get(bucketId) ?? new Map();
+            byDay.set(day, Math.max(byDay.get(day) ?? 0, run.settlementEndMs));
+            settlementEnds.set(bucketId, byDay);
+            const startsByDay = sourceStarts.get(bucketId) ?? new Map();
+            startsByDay.set(day, Math.min(startsByDay.get(day) ?? Number.POSITIVE_INFINITY, run.sourceStartMs));
+            sourceStarts.set(bucketId, startsByDay);
+            runSpans.set(bucketId, [...(runSpans.get(bucketId) ?? []), {
+                    creditedMs,
+                    endMs: options.dwellSeconds > 0 ? run.startMs + creditedMs * (index + 1) : run.endMs,
+                    startMs: options.dwellSeconds > 0 ? run.startMs + creditedMs * index : run.startMs,
+                    sourceStartMs: run.sourceStartMs
+                }]);
+        }
+    }
+    const result = new Map();
+    for (const [bucketId, byDay] of totals) {
+        const spansByDay = new Map();
+        for (const span of runSpans.get(bucketId) ?? []) {
+            const day = localDay(new Date(span.startMs));
+            spansByDay.set(day, [...(spansByDay.get(day) ?? []), span]);
+        }
+        const perDay = new Map();
+        for (const [day, sums] of byDay) {
+            // Floor, not round. A share of an odd-length slice is fractional, and rounding each bucket
+            // up independently can push the day one second past the wall clock it occupied — breaking
+            // the one invariant this shape exists to guarantee. Flooring errs the way the design prefers.
+            const seconds = Math.floor(sums.creditedMs / 1000);
+            perDay.set(day, {
+                activeSeconds: Math.floor(sums.activeMs / 1000),
+                // The blocks are the row: the same runs, coalesced for reading, sharing out the same total.
+                blocks: wholeSeconds(coalesceBlocks(spansByDay.get(day) ?? [], 0), seconds),
+                settlementEndMs: settlementEnds.get(bucketId)?.get(day) ?? 0,
+                sourceStartMs: sourceStarts.get(bucketId)?.get(day) ?? 0,
+                seconds
+            });
+        }
+        result.set(bucketId, perDay);
+    }
+    return result;
+};
+/** The lower of two confidences, treating "no Coding Agent involved" as absent rather than zero. */
+const weakerConfidence = (a, b) => {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return Math.min(a, b);
+};
+const bucketId = (kind, ticketKey) => `${kind}\u0000${ticketKey ?? ""}`;
+class MissingDayAttributionError extends Data.TaggedError("MissingDayAttributionError") {
+}
+/**
+ * Fold per-session active windows onto Issue Keys, dividing every overlap between *distinct* keys.
+ *
+ * Bucketing happens before sharing, which is the whole point: two sessions on the same Issue Key
+ * union their windows and lose nothing, while two sessions on different keys split the instants they
+ * share. Below-floor and unplaced time gets its own buckets so neither can be silently dropped nor
+ * silently proposed — and both still take part in the split, because they occupied real time.
+ */
+export const splitCredits = (windows, attributions, options) => {
+    const bySession = new Map(attributions.map((attribution) => [attribution.sessionId, attribution]));
+    const spansByBucket = new Map();
+    const metaByBucket = new Map();
+    // Which sessions contributed to a bucket *on a given day*, not merely to the bucket.
+    //
+    // A week's run emits one row per day, and each row's evidence has to be that day's. Carrying the
+    // bucket's whole session set would ask a Coding Agent to describe Monday's work from Friday's
+    // prompts — and that sentence is written verbatim into a Clockify description and a Jira worklog.
+    const sessionsByBucketDay = new Map();
+    const evidenceByBucketDay = new Map();
+    const dayKey = (bucketId, day) => `${bucketId}\u0000${day}`;
+    for (const session of windows) {
+        const attribution = bySession.get(session.sessionId);
+        const ticketKey = attribution?.ticketKey ?? null;
+        const kind = ticketKey === null
+            ? "unattributed"
+            : attribution?.belowConfidenceFloor === true
+                ? "withheld"
+                : "attributed";
+        const id = bucketId(kind, ticketKey);
+        spansByBucket.set(id, [...(spansByBucket.get(id) ?? []), ...session.spans]);
+        // Session windows are already day-bounded, so a span belongs to exactly one day.
+        for (const span of session.spans) {
+            const key = dayKey(id, localDay(new Date(span.startMs)));
+            sessionsByBucketDay.set(key, (sessionsByBucketDay.get(key) ?? new Set()).add(session.sessionId));
+            const previous = evidenceByBucketDay.get(key);
+            const signal = attribution?.signal ?? "none";
+            const confidence = attribution?.confidence ?? null;
+            evidenceByBucketDay.set(key, {
+                signal: previous === undefined || signalRank(signal) > signalRank(previous.signal) ? signal : previous.signal,
+                confidence: previous === undefined ? confidence : weakerConfidence(previous.confidence, confidence)
+            });
+        }
+        const existing = metaByBucket.get(id);
+        metaByBucket.set(id, {
+            kind,
+            ticketKey,
+            sessions: new Set([...(existing?.sessions ?? []), session.sessionId])
+        });
+    }
+    const shared = shareBetweenBuckets(new Map([...spansByBucket.entries()].map(([id, spans]) => [id, mergeSpansWithinDays(spans)])), {
+        attributed: (id) => metaByBucket.get(id)?.kind === "attributed",
+        coveredByCertain: (id, activeIds) => {
+            const held = metaByBucket.get(id);
+            return held?.kind === "withheld" && activeIds.some((other) => {
+                const certain = metaByBucket.get(other);
+                return certain?.kind === "attributed" && certain.ticketKey === held.ticketKey;
+            });
+        },
+        dwellSeconds: options?.dwellSeconds ?? DEFAULT_DWELL_SECONDS
+    });
+    const attributed = [];
+    const withheld = [];
+    const unattributed = [];
+    for (const [id, perDay] of shared) {
+        const meta = metaByBucket.get(id);
+        if (meta === undefined)
+            continue;
+        for (const [day, credit] of perDay) {
+            if (credit.seconds <= 0)
+                continue;
+            const daySessions = sessionsByBucketDay.get(dayKey(id, day)) ?? meta.sessions;
+            const dayEvidence = evidenceByBucketDay.get(dayKey(id, day));
+            if (dayEvidence === undefined) {
+                throw new MissingDayAttributionError({ message: "Scheduled credit has no same-day evidence" });
+            }
+            if (meta.kind === "unattributed") {
+                const cwds = [
+                    ...new Set([...daySessions].flatMap((sessionId) => {
+                        const cwd = options?.cwdBySession?.get(sessionId);
+                        return cwd === undefined ? [] : [cwd];
+                    }))
+                ].sort();
+                unattributed.push({ day, seconds: credit.seconds, sessionCount: daySessions.size, cwds });
+                continue;
+            }
+            const row = {
+                ticketKey: meta.ticketKey ?? "",
+                day,
+                seconds: credit.seconds,
+                signal: dayEvidence.signal,
+                confidence: dayEvidence.confidence,
+                activeSeconds: credit.activeSeconds,
+                blocks: credit.blocks,
+                sourceStartMs: credit.sourceStartMs,
+                settlementEndMs: credit.settlementEndMs,
+                sessionIds: [...daySessions].sort()
+            };
+            if (meta.kind === "withheld")
+                withheld.push(row);
+            else
+                attributed.push(row);
+        }
+    }
+    const byDayThenTicket = (a, b) => (a.day === b.day ? a.ticketKey.localeCompare(b.ticketKey) : a.day.localeCompare(b.day));
+    return {
+        attributed: attributed.sort(byDayThenTicket),
+        withheld: withheld.sort(byDayThenTicket),
+        unattributed: unattributed.sort((a, b) => a.day.localeCompare(b.day))
+    };
+};
+/** Both systems: what reconciliation means unless someone says otherwise. */
+export const bothSides = { clockify: true, jira: true };
+export const buildSessionProposals = (credits, recorded, options) => {
+    const sides = options.sides ?? bothSides;
+    const excluded = new Set(options.excludedDays);
+    const recordedByBucket = new Map(recorded.map((r) => [`${r.ticketKey}\u0000${r.day}`, r]));
+    const consumptionRows = [
+        ...recorded.map((row) => ({ ticketKey: row.ticketKey, day: row.day, intervals: row.intervals ?? [] })),
+        ...(options.consumptionRows ?? [])
+    ];
+    const gap = (sessionSeconds, recordedSeconds, minimumSeconds) => {
+        const delta = sessionSeconds - recordedSeconds;
+        return delta >= minimumSeconds ? delta : 0;
+    };
+    return credits
+        .filter((credit) => !excluded.has(credit.day))
+        .map((credit) => {
+        const existing = recordedByBucket.get(`${credit.ticketKey}\u0000${credit.day}`);
+        const clockifySeconds = existing?.clockifySeconds ?? 0;
+        const jiraSeconds = existing?.jiraSeconds ?? 0;
+        const sourceRowId = `${credit.day}:${credit.ticketKey}`;
+        const heldByBlock = SourceConsumption.consumptionForBlocks(consumptionRows, sourceRowId, credit.blocks, sides, options.sourceEntries);
+        const ambiguousClockify = SourceConsumption.unlinkedClockifyOverlaps(credit.blocks, options.consumptionRows ?? [], options.sourceEntries);
+        const blocks = credit.blocks.map((block, index) => {
+            const held = heldByBlock[index] ?? { clockify: 0, jira: 0 };
+            return {
+                ...block,
+                ...(sides.clockify && ambiguousClockify[index] && { clockifyRefusal: "unlinked-overlap" }),
+                ...(held.clockify > 0 && { clockifyConsumedSeconds: Math.min(block.seconds, held.clockify) }),
+                ...(held.jira > 0 && { jiraConsumedSeconds: Math.min(block.seconds, held.jira) })
+            };
+        });
+        const correctedClockifySeconds = blocks.reduce((sum, block) => sum + (block.clockifyConsumedSeconds ?? 0), 0);
+        const correctedJiraSeconds = blocks.reduce((sum, block) => sum + (block.jiraConsumedSeconds ?? 0), 0);
+        return {
+            ticketKey: credit.ticketKey,
+            day: credit.day,
+            signal: credit.signal,
+            confidence: credit.confidence,
+            blocks,
+            sourceStartMs: credit.sourceStartMs,
+            settlementEndMs: credit.settlementEndMs,
+            sessionSeconds: credit.seconds,
+            activeSeconds: credit.activeSeconds,
+            clockifySeconds,
+            jiraSeconds,
+            recordedIntervals: (existing?.intervals ?? []).flatMap((interval) => interval.source === undefined || interval.startMs === undefined || interval.endMs === undefined
+                ? []
+                : [{ source: interval.source, startMs: interval.startMs, endMs: interval.endMs }]),
+            // Zero for a side that is out of scope, never the whole day: its tally was not read, so the
+            // only defensible statement about its gap is that this run makes none.
+            clockifyDelta: sides.clockify ? gap(credit.seconds, clockifySeconds + correctedClockifySeconds, 1) : 0,
+            jiraDelta: sides.jira ? gap(credit.seconds, jiraSeconds + correctedJiraSeconds, options.minimumSeconds) : 0,
+            sessionIds: credit.sessionIds
+        };
+    })
+        .filter((proposal) => proposal.clockifyDelta > 0 || proposal.jiraDelta > 0);
+};
+// ---------------------------------------------------------------------------
+// Session digest
+// ---------------------------------------------------------------------------
+const DEFAULT_DIGEST_CHARS = 4000;
+/**
+ * A compact, bounded digest of a session's prompts for a Coding Agent to read. Takes text from
+ * the start of the session — where the task is stated — and stops at the character budget, so
+ * one very long transcript cannot dominate the prompt.
+ */
+export const buildSessionDigest = (texts, options) => {
+    const maxChars = options?.maxChars ?? DEFAULT_DIGEST_CHARS;
+    const parts = [];
+    let length = 0;
+    for (const raw of texts) {
+        const text = raw.trim();
+        if (text === "")
+            continue;
+        const remaining = maxChars - length;
+        if (remaining <= 0)
+            break;
+        const clipped = text.length > remaining ? text.slice(0, remaining) : text;
+        parts.push(clipped);
+        length += clipped.length + 1;
+    }
+    return parts.join("\n");
+};
+//# sourceMappingURL=sessions.js.map