agentplane 0.2.25 → 0.3.1

package/dist/harness/reconcile.d.ts

@@ -0,0 +1,37 @@
+import type { OrchestrationState } from "./state-machine.js";
+export type ReconcileRunningEntry = {
+    issueId: string;
+    issueIdentifier: string;
+    state: string;
+    orchestrationState: OrchestrationState;
+    startedAt: Date;
+    lastActivityAt: Date;
+};
+export type ReconcileObservedIssue = {
+    id: string;
+    state: string;
+    assignedToWorker: boolean;
+};
+export type ReconcileConfig = {
+    activeStates: string[];
+    terminalStates: string[];
+    stallTimeoutMs: number;
+};
+export type ReconcileAction = {
+    type: "stop_running";
+    issueId: string;
+    reason: "terminal" | "non_active" | "not_routed";
+} | {
+    type: "restart_stalled";
+    issueId: string;
+    elapsedMs: number;
+} | {
+    type: "keep_running";
+    issueId: string;
+};
+export type ReconcileResult = {
+    nextRunning: ReconcileRunningEntry[];
+    actions: ReconcileAction[];
+};
+export declare function reconcileFirst(running: readonly ReconcileRunningEntry[], observed: readonly ReconcileObservedIssue[], config: ReconcileConfig, now: Date): ReconcileResult;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/harness/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/harness/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,SAAS,EAAE,IAAI,CAAC;IAChB,cAAc,EAAE,IAAI,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,YAAY,CAAA;CAAE,GAC3F;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC;AAWF,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,EAC3C,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,IAAI,GACR,eAAe,CA0CjB"}

package/dist/harness/reconcile.js

@@ -0,0 +1,42 @@
+function normalizeState(value) {
+    return value.trim().toLowerCase();
+}
+function isStateInSet(value, set) {
+    const normalized = normalizeState(value);
+    return set.some((item) => normalizeState(item) === normalized);
+}
+export function reconcileFirst(running, observed, config, now) {
+    const observedById = new Map(observed.map((issue) => [issue.id, issue]));
+    const nextRunning = [];
+    const actions = [];
+    for (const entry of running) {
+        const observedIssue = observedById.get(entry.issueId);
+        if (!observedIssue) {
+            actions.push({ type: "stop_running", issueId: entry.issueId, reason: "non_active" });
+            continue;
+        }
+        if (isStateInSet(observedIssue.state, config.terminalStates)) {
+            actions.push({ type: "stop_running", issueId: entry.issueId, reason: "terminal" });
+            continue;
+        }
+        if (!observedIssue.assignedToWorker) {
+            actions.push({ type: "stop_running", issueId: entry.issueId, reason: "not_routed" });
+            continue;
+        }
+        if (!isStateInSet(observedIssue.state, config.activeStates)) {
+            actions.push({ type: "stop_running", issueId: entry.issueId, reason: "non_active" });
+            continue;
+        }
+        const elapsedMs = Math.max(0, now.getTime() - entry.lastActivityAt.getTime());
+        if (config.stallTimeoutMs > 0 && elapsedMs > config.stallTimeoutMs) {
+            actions.push({ type: "restart_stalled", issueId: entry.issueId, elapsedMs });
+            continue;
+        }
+        actions.push({ type: "keep_running", issueId: entry.issueId });
+        nextRunning.push({ ...entry, state: observedIssue.state });
+    }
+    return {
+        nextRunning,
+        actions,
+    };
+}

package/dist/harness/retry-policy.d.ts

@@ -0,0 +1,31 @@
+export type RetryReasonCode = "continuation_needed" | "worker_exit_abnormal" | "worker_spawn_failed" | "stalled_timeout" | "poll_failed" | "no_slots" | "reconcile_conflict";
+export type RetryDelayType = "continuation" | "failure";
+export type RetryPolicy = {
+    continuationDelayMs: number;
+    failureBaseDelayMs: number;
+    maxBackoffMs: number;
+    maxAttempts: number;
+};
+export type RetryEntry = {
+    issueId: string;
+    attempt: number;
+    dueAtMs: number;
+    reasonCode: RetryReasonCode;
+    reasonMessage?: string;
+    delayType: RetryDelayType;
+};
+export declare function computeRetryDelayMs(attempt: number, delayType: RetryDelayType, policy?: RetryPolicy): number;
+export declare function scheduleRetryEntry(opts: {
+    issueId: string;
+    attempt: number;
+    reasonCode: RetryReasonCode;
+    reasonMessage?: string;
+    delayType: RetryDelayType;
+    nowMs: number;
+    policy?: RetryPolicy;
+}): RetryEntry;
+export declare function canRetry(attempt: number, policy?: RetryPolicy): {
+    allowed: boolean;
+    terminal: boolean;
+};
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/harness/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../src/harness/retry-policy.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,qBAAqB,GACrB,sBAAsB,GACtB,qBAAqB,GACrB,iBAAiB,GACjB,aAAa,GACb,UAAU,GACV,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,eAAe,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,cAAc,CAAC;CAC3B,CAAC;AASF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,EACzB,MAAM,GAAE,WAA4B,GACnC,MAAM,CAOR;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,eAAe,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,cAAc,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,UAAU,CAYb;AAED,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAA4B,GACnC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKzC"}

package/dist/harness/retry-policy.js

@@ -0,0 +1,33 @@
+const DEFAULT_POLICY = {
+    continuationDelayMs: 1000,
+    failureBaseDelayMs: 10_000,
+    maxBackoffMs: 300_000,
+    maxAttempts: 5,
+};
+export function computeRetryDelayMs(attempt, delayType, policy = DEFAULT_POLICY) {
+    if (delayType === "continuation" && attempt <= 1) {
+        return policy.continuationDelayMs;
+    }
+    const power = Math.max(0, Math.min(attempt - 1, 10));
+    const delayed = policy.failureBaseDelayMs * 2 ** power;
+    return Math.min(delayed, policy.maxBackoffMs);
+}
+export function scheduleRetryEntry(opts) {
+    const policy = opts.policy ?? DEFAULT_POLICY;
+    const safeAttempt = Math.max(1, opts.attempt);
+    const delayMs = computeRetryDelayMs(safeAttempt, opts.delayType, policy);
+    return {
+        issueId: opts.issueId,
+        attempt: safeAttempt,
+        dueAtMs: opts.nowMs + delayMs,
+        reasonCode: opts.reasonCode,
+        reasonMessage: opts.reasonMessage,
+        delayType: opts.delayType,
+    };
+}
+export function canRetry(attempt, policy = DEFAULT_POLICY) {
+    if (attempt < policy.maxAttempts) {
+        return { allowed: true, terminal: false };
+    }
+    return { allowed: false, terminal: true };
+}

package/dist/harness/scheduler.d.ts

@@ -0,0 +1,18 @@
+export type SchedulerIssue = {
+    id: string;
+    state: string;
+    priority?: number | null;
+    createdAt?: string | null;
+};
+export type SchedulerEntry = {
+    issue: SchedulerIssue;
+    workerId: string;
+};
+export type SchedulerLimits = {
+    maxConcurrent: number;
+    maxConcurrentByState?: Record<string, number>;
+};
+export declare function sortIssuesForDispatch(issues: readonly SchedulerIssue[]): SchedulerIssue[];
+export declare function canDispatchIssue(issue: SchedulerIssue, running: readonly SchedulerEntry[], limits: SchedulerLimits): boolean;
+export declare function planDispatch(candidates: readonly SchedulerIssue[], running: readonly SchedulerEntry[], limits: SchedulerLimits): SchedulerIssue[];
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/harness/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/harness/scheduler.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C,CAAC;AAoBF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,EAAE,CAYzF;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,MAAM,EAAE,eAAe,GACtB,OAAO,CAaT;AAED,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,cAAc,EAAE,EACrC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,MAAM,EAAE,eAAe,GACtB,cAAc,EAAE,CAYlB"}

package/dist/harness/scheduler.js

@@ -0,0 +1,55 @@
+function normalizeState(value) {
+    return value.trim().toLowerCase();
+}
+function createdAtMicros(value) {
+    if (!value)
+        return Number.MAX_SAFE_INTEGER;
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        return Number.MAX_SAFE_INTEGER;
+    return parsed * 1000;
+}
+function priorityRank(priority) {
+    if (typeof priority !== "number")
+        return 5;
+    if (!Number.isInteger(priority))
+        return 5;
+    if (priority < 1 || priority > 4)
+        return 5;
+    return priority;
+}
+export function sortIssuesForDispatch(issues) {
+    return issues.toSorted((a, b) => {
+        const aPriority = priorityRank(a.priority);
+        const bPriority = priorityRank(b.priority);
+        if (aPriority !== bPriority)
+            return aPriority - bPriority;
+        const aCreated = createdAtMicros(a.createdAt);
+        const bCreated = createdAtMicros(b.createdAt);
+        if (aCreated !== bCreated)
+            return aCreated - bCreated;
+        return a.id.localeCompare(b.id);
+    });
+}
+export function canDispatchIssue(issue, running, limits) {
+    const totalRunning = running.length;
+    if (totalRunning >= limits.maxConcurrent)
+        return false;
+    const stateKey = normalizeState(issue.state);
+    const stateLimitRaw = limits.maxConcurrentByState?.[stateKey];
+    const stateLimit = typeof stateLimitRaw === "number" && stateLimitRaw > 0 ? stateLimitRaw : limits.maxConcurrent;
+    const stateUsed = running.filter((entry) => normalizeState(entry.issue.state) === stateKey).length;
+    return stateUsed < stateLimit;
+}
+export function planDispatch(candidates, running, limits) {
+    const ordered = sortIssuesForDispatch(candidates);
+    const accepted = [];
+    const shadowRunning = [...running];
+    for (const issue of ordered) {
+        if (!canDispatchIssue(issue, shadowRunning, limits))
+            continue;
+        accepted.push(issue);
+        shadowRunning.push({ issue, workerId: `planned:${issue.id}` });
+    }
+    return accepted;
+}

package/dist/harness/state-machine.d.ts

@@ -0,0 +1,17 @@
+export type OrchestrationState = "unclaimed" | "claimed" | "running" | "retry_queued" | "released";
+export type OrchestrationEvent = "claim" | "start" | "queue_retry" | "release" | "mark_released" | "reset";
+export type TransitionResult = {
+    ok: true;
+    next: OrchestrationState;
+} | {
+    ok: false;
+    code: "ORCH_INVALID_TRANSITION";
+    message: string;
+    current: OrchestrationState;
+    event: OrchestrationEvent;
+};
+export declare function transitionOrchestrationState(current: OrchestrationState, event: OrchestrationEvent, opts?: {
+    strict?: boolean;
+}): TransitionResult;
+export declare function assertTransitionOrThrow(current: OrchestrationState, event: OrchestrationEvent): OrchestrationState;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/harness/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/harness/state-machine.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAEnG,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,OAAO,GACP,aAAa,GACb,SAAS,GACT,eAAe,GACf,OAAO,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACtC;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,kBAAkB,CAAC;CAC3B,CAAC;AAqDN,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1B,gBAAgB,CAalB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAMpB"}

package/dist/harness/state-machine.js

@@ -0,0 +1,70 @@
+const TRANSITIONS = {
+    unclaimed: {
+        claim: "claimed",
+        start: "unclaimed",
+        queue_retry: "unclaimed",
+        release: "released",
+        mark_released: "released",
+        reset: "unclaimed",
+    },
+    claimed: {
+        claim: "claimed",
+        start: "running",
+        queue_retry: "retry_queued",
+        release: "released",
+        mark_released: "released",
+        reset: "unclaimed",
+    },
+    running: {
+        claim: "running",
+        start: "running",
+        queue_retry: "retry_queued",
+        release: "released",
+        mark_released: "released",
+        reset: "unclaimed",
+    },
+    retry_queued: {
+        claim: "claimed",
+        start: "running",
+        queue_retry: "retry_queued",
+        release: "released",
+        mark_released: "released",
+        reset: "unclaimed",
+    },
+    released: {
+        claim: "claimed",
+        start: "released",
+        queue_retry: "released",
+        release: "released",
+        mark_released: "released",
+        reset: "unclaimed",
+    },
+};
+const STRICT_ALLOWED = {
+    unclaimed: ["claim", "mark_released", "reset"],
+    claimed: ["start", "queue_retry", "release", "reset"],
+    running: ["queue_retry", "release", "reset"],
+    retry_queued: ["claim", "start", "release", "reset"],
+    released: ["claim", "reset"],
+};
+export function transitionOrchestrationState(current, event, opts) {
+    const strict = opts?.strict ?? true;
+    if (strict && !STRICT_ALLOWED[current].includes(event)) {
+        return {
+            ok: false,
+            code: "ORCH_INVALID_TRANSITION",
+            message: `Invalid transition: ${current} --${event}--> ?`,
+            current,
+            event,
+        };
+    }
+    const next = TRANSITIONS[current][event];
+    return { ok: true, next };
+}
+export function assertTransitionOrThrow(current, event) {
+    const result = transitionOrchestrationState(current, event, { strict: true });
+    if (!result.ok) {
+        throw new Error(`${result.code}: ${result.message}`);
+    }
+    return result.next;
+}

package/dist/harness/token-accounting.d.ts

@@ -0,0 +1,19 @@
+export type TokenTotals = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+};
+export type TokenUsageEvent = {
+    threadId: string;
+    payload: Record<string, unknown>;
+};
+export type TokenAccumulator = {
+    byThread: Record<string, TokenTotals>;
+    global: TokenTotals;
+};
+export declare function createTokenAccumulator(): TokenAccumulator;
+export declare function applyTokenUsageEvent(state: TokenAccumulator, event: TokenUsageEvent): {
+    state: TokenAccumulator;
+    accepted: boolean;
+};
+//# sourceMappingURL=token-accounting.d.ts.map

package/dist/harness/token-accounting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-accounting.d.ts","sourceRoot":"","sources":["../../src/harness/token-accounting.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACtC,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAwDF,wBAAgB,sBAAsB,IAAI,gBAAgB,CAKzD;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,eAAe,GACrB;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAuBhD"}

package/dist/harness/token-accounting.js

@@ -0,0 +1,77 @@
+const ZERO_TOTALS = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+};
+function safeInt(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return Math.trunc(value);
+    if (typeof value === "string" && /^\d+$/.test(value))
+        return Number.parseInt(value, 10);
+    return null;
+}
+function extractAbsoluteTotals(payload) {
+    const tokenUsage = payload.tokenUsage;
+    if (tokenUsage && typeof tokenUsage === "object" && !Array.isArray(tokenUsage)) {
+        const total = tokenUsage.total;
+        if (total && typeof total === "object" && !Array.isArray(total)) {
+            const totalObj = total;
+            const input = safeInt(totalObj.inputTokens);
+            const output = safeInt(totalObj.outputTokens);
+            const all = safeInt(totalObj.totalTokens);
+            if (input !== null && output !== null && all !== null) {
+                return { inputTokens: input, outputTokens: output, totalTokens: all };
+            }
+        }
+    }
+    const info = payload.info;
+    if (info && typeof info === "object" && !Array.isArray(info)) {
+        const totalUsage = info.total_token_usage;
+        if (totalUsage && typeof totalUsage === "object" && !Array.isArray(totalUsage)) {
+            const usage = totalUsage;
+            const input = safeInt(usage.input_tokens);
+            const output = safeInt(usage.output_tokens);
+            const all = safeInt(usage.total_tokens);
+            if (input !== null && output !== null && all !== null) {
+                return { inputTokens: input, outputTokens: output, totalTokens: all };
+            }
+        }
+    }
+    return null;
+}
+function mergeGlobal(byThread) {
+    const global = { ...ZERO_TOTALS };
+    for (const totals of Object.values(byThread)) {
+        global.inputTokens += totals.inputTokens;
+        global.outputTokens += totals.outputTokens;
+        global.totalTokens += totals.totalTokens;
+    }
+    return global;
+}
+export function createTokenAccumulator() {
+    return {
+        byThread: {},
+        global: { ...ZERO_TOTALS },
+    };
+}
+export function applyTokenUsageEvent(state, event) {
+    const absolute = extractAbsoluteTotals(event.payload);
+    if (!absolute) {
+        return { state, accepted: false };
+    }
+    const prev = state.byThread[event.threadId] ?? { ...ZERO_TOTALS };
+    if (absolute.totalTokens < prev.totalTokens) {
+        return { state, accepted: false };
+    }
+    const nextByThread = {
+        ...state.byThread,
+        [event.threadId]: absolute,
+    };
+    return {
+        accepted: true,
+        state: {
+            byThread: nextByThread,
+            global: mergeGlobal(nextByThread),
+        },
+    };
+}

package/dist/harness/workspace-safety.d.ts

@@ -0,0 +1,14 @@
+export declare function sanitizeWorkspaceKey(raw: string): string;
+export declare function resolveWorkspacePath(root: string, key: string): string;
+export declare function validateWorkspacePathInvariants(opts: {
+    root: string;
+    workspacePath: string;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    code: "WORKSPACE_EQUALS_ROOT" | "WORKSPACE_OUTSIDE_ROOT" | "WORKSPACE_SYMLINK_ESCAPE" | "WORKSPACE_PATH_UNREADABLE";
+    path: string;
+    message: string;
+}>;
+//# sourceMappingURL=workspace-safety.d.ts.map

package/dist/harness/workspace-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-safety.d.ts","sourceRoot":"","sources":["../../src/harness/workspace-safety.ts"],"names":[],"mappings":"AAGA,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAsB,+BAA+B,CAAC,IAAI,EAAE;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CACP;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EACA,uBAAuB,GACvB,wBAAwB,GACxB,0BAA0B,GAC1B,2BAA2B,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CACJ,CAqDA"}

package/dist/harness/workspace-safety.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export function sanitizeWorkspaceKey(raw) {
+    const normalized = raw.trim();
+    if (normalized.length === 0)
+        return "issue";
+    return normalized.replaceAll(/[^a-zA-Z0-9._-]/g, "_");
+}
+export function resolveWorkspacePath(root, key) {
+    return path.join(path.resolve(root), sanitizeWorkspaceKey(key));
+}
+export async function validateWorkspacePathInvariants(opts) {
+    const root = path.resolve(opts.root);
+    const workspace = path.resolve(opts.workspacePath);
+    const rootPrefix = `${root}${path.sep}`;
+    if (workspace === root) {
+        return {
+            ok: false,
+            code: "WORKSPACE_EQUALS_ROOT",
+            path: workspace,
+            message: "Workspace path must not equal workspace root.",
+        };
+    }
+    if (!(workspace === root || workspace.startsWith(rootPrefix))) {
+        return {
+            ok: false,
+            code: "WORKSPACE_OUTSIDE_ROOT",
+            path: workspace,
+            message: "Workspace path escapes configured workspace root.",
+        };
+    }
+    const relative = path.relative(root, workspace);
+    const segments = relative.split(path.sep).filter((s) => s.length > 0);
+    let cursor = root;
+    for (const segment of segments) {
+        cursor = path.join(cursor, segment);
+        try {
+            const stat = await fs.lstat(cursor);
+            if (stat.isSymbolicLink()) {
+                return {
+                    ok: false,
+                    code: "WORKSPACE_SYMLINK_ESCAPE",
+                    path: cursor,
+                    message: "Workspace path contains a symlink component.",
+                };
+            }
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT") {
+                return { ok: true };
+            }
+            return {
+                ok: false,
+                code: "WORKSPACE_PATH_UNREADABLE",
+                path: cursor,
+                message: `Workspace path cannot be validated: ${err.message}`,
+            };
+        }
+    }
+    return { ok: true };
+}

package/dist/recipes/bundled-recipes.d.ts

@@ -4,10 +4,14 @@ export type BundledRecipesCatalog = {
         id: string;
         summary: string;
         description?: string;
+        source_path?: string;
         versions: {
             version: string;
         }[];
     }[];
 };
+export type BundledRecipeEntry = BundledRecipesCatalog["recipes"][number];
 export declare const BUNDLED_RECIPES_CATALOG: BundledRecipesCatalog;
+export declare function resolveBundledRecipeSourcePath(recipeId: string): string | null;
+export declare function getBundledRecipeEntry(recipeId: string): BundledRecipeEntry | null;
 //# sourceMappingURL=bundled-recipes.d.ts.map

package/dist/recipes/bundled-recipes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundled-recipes.d.ts","sourceRoot":"","sources":["../../src/recipes/bundled-recipes.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAAG;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACjC,EAAE,CAAC;CACL,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,qBAGrC,CAAC"}
+{"version":3,"file":"bundled-recipes.d.ts","sourceRoot":"","sources":["../../src/recipes/bundled-recipes.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,qBAAqB,GAAG;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACjC,EAAE,CAAC;CACL,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB,EAAE,qBAGrC,CAAC;AAEF,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAEjF"}

package/dist/recipes/bundled-recipes.js

@@ -1,4 +1,15 @@
+import { fileURLToPath } from "node:url";
 export const BUNDLED_RECIPES_CATALOG = {
     schema_version: 1,
     recipes: [],
 };
+export function resolveBundledRecipeSourcePath(recipeId) {
+    const entry = getBundledRecipeEntry(recipeId);
+    const sourcePath = entry?.source_path?.trim();
+    if (!sourcePath)
+        return null;
+    return fileURLToPath(new URL(`../../assets/${sourcePath.replace(/^\/+/, "")}`, import.meta.url));
+}
+export function getBundledRecipeEntry(recipeId) {
+    return BUNDLED_RECIPES_CATALOG.recipes.find((recipe) => recipe.id === recipeId) ?? null;
+}

package/dist/shared/errors.d.ts

@@ -17,6 +17,12 @@ export type JsonErrorGuidance = {
         reason: string;
         reasonCode?: string;
     };
+    reasonDecode?: {
+        code: string;
+        category: string;
+        summary: string;
+        action: string;
+    };
 };
 export declare function formatJsonError(err: CliError, guidance?: JsonErrorGuidance): string;
 //# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,MAAM,GACN,OAAO,GACP,WAAW,GACX,WAAW,GACX,YAAY,CAAC;AAEjB,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,SAAS,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CAMF;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAcnF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,MAAM,GACN,OAAO,GACP,WAAW,GACX,WAAW,GACX,YAAY,CAAC;AAEjB,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,SAAS,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CAMF;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,YAAY,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAenF"}

package/dist/shared/errors.js

@@ -17,6 +17,7 @@ export function formatJsonError(err, guidance) {
             context: err.context ?? undefined,
             hint: guidance?.hint,
             next_action: guidance?.nextAction,
+            reason_decode: guidance?.reasonDecode,
         },
     }, null, 2);
 }

package/dist/shared/policy-gateway.d.ts

@@ -0,0 +1,15 @@
+export type PolicyGatewayFlavor = "codex" | "claude";
+export type PolicyGatewayFileName = "AGENTS.md" | "CLAUDE.md";
+export declare const POLICY_GATEWAY_FILE_BY_FLAVOR: Record<PolicyGatewayFlavor, PolicyGatewayFileName>;
+export type PolicyGatewayResolution = {
+    flavor: PolicyGatewayFlavor;
+    fileName: PolicyGatewayFileName;
+    absPath: string;
+};
+export declare function policyGatewayFileName(flavor: PolicyGatewayFlavor): PolicyGatewayFileName;
+export declare function renderPolicyGatewayTemplateText(text: string, fileName: PolicyGatewayFileName): string;
+export declare function resolvePolicyGatewayForRepo(opts: {
+    gitRoot: string;
+    fallbackFlavor?: PolicyGatewayFlavor;
+}): Promise<PolicyGatewayResolution>;
+//# sourceMappingURL=policy-gateway.d.ts.map

package/dist/shared/policy-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-gateway.d.ts","sourceRoot":"","sources":["../../src/shared/policy-gateway.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,CAAC;AACrD,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE9D,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CAG5F,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAWF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,GAAG,qBAAqB,CAExF;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAUR;AAED,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAoBnC"}

package/dist/shared/policy-gateway.js

@@ -0,0 +1,49 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+export const POLICY_GATEWAY_FILE_BY_FLAVOR = {
+    codex: "AGENTS.md",
+    claude: "CLAUDE.md",
+};
+async function exists(absPath) {
+    try {
+        await access(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function policyGatewayFileName(flavor) {
+    return POLICY_GATEWAY_FILE_BY_FLAVOR[flavor];
+}
+export function renderPolicyGatewayTemplateText(text, fileName) {
+    const collapsed = text
+        .replaceAll("{{POLICY_GATEWAY_FILE}}", fileName)
+        .replaceAll("AGENTS.md or CLAUDE.md", fileName)
+        .replaceAll("AGENTS.md and CLAUDE.md", fileName)
+        .replaceAll("AGENTS.md|CLAUDE.md", fileName);
+    if (fileName === "AGENTS.md")
+        return collapsed;
+    return collapsed
+        .replaceAll("AGENTS.md", "CLAUDE.md")
+        .replaceAll("AGENTS_POLICY", "CLAUDE_POLICY");
+}
+export async function resolvePolicyGatewayForRepo(opts) {
+    const codexPath = path.join(opts.gitRoot, POLICY_GATEWAY_FILE_BY_FLAVOR.codex);
+    const claudePath = path.join(opts.gitRoot, POLICY_GATEWAY_FILE_BY_FLAVOR.claude);
+    const hasCodex = await exists(codexPath);
+    const hasClaude = await exists(claudePath);
+    if (hasCodex) {
+        return { flavor: "codex", fileName: "AGENTS.md", absPath: codexPath };
+    }
+    if (hasClaude) {
+        return { flavor: "claude", fileName: "CLAUDE.md", absPath: claudePath };
+    }
+    const fallback = opts.fallbackFlavor ?? "codex";
+    const fileName = policyGatewayFileName(fallback);
+    return {
+        flavor: fallback,
+        fileName,
+        absPath: path.join(opts.gitRoot, fileName),
+    };
+}

package/dist/shared/protected-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../src/shared/protected-paths.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAQF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,CAkBvF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,iBAAiB,GAAG,IAAI,CA6B3B"}
+{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../src/shared/protected-paths.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAQF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,CAkBvF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,iBAAiB,GAAG,IAAI,CA8B3B"}