@telora/daemon 0.21.12 → 0.21.81

package/dist/drift/staleness.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Staleness signal: is the RUNNING daemon behind the latest published release?
+ *
+ * Consumed by `telora-daemon status` and `telora-daemon session-state` to
+ * surface a one-line warning when the running daemon version is behind the
+ * latest published @telora/daemon. The CLI binary executing those commands may
+ * be a DIFFERENT install than the running daemon (repo checkout vs npx cache),
+ * so the running version comes from daemon.meta.json -- stamped by the daemon
+ * itself at startup -- never from the CLI's own package.json.
+ *
+ * Design constraints:
+ * - Silent degradation: never writes to stdout; any failure (no meta, legacy
+ *   meta without a version stamp, daemon not running, registry unreachable)
+ *   returns null so callers print their normal output unchanged. The
+ *   underlying checkForUpdates console.warns on failure -- that goes to
+ *   stderr, which the session-state stdout contract tolerates.
+ * - Cached: the registry answer is cached in the global state dir
+ *   (version-check-cache.json) with a 6h TTL. An EXPIRED cache is never used
+ *   as a fallback -- a failed refresh returns null rather than reporting
+ *   staleness from old data (no stale-cache false positives).
+ * - Latency split: session-state is CACHE-ONLY (zero network -- the
+ *   SessionStart hook blocks Claude Code on this command, and an unreachable
+ *   registry would otherwise hang it for the full fetch timeout). The async
+ *   half of "async or cached" lives in the RUNNING DAEMON, which refreshes
+ *   the cache on a timer (startVersionCacheRefreshLoop) in every install
+ *   mode, including npx with auto-update disabled -- the case the signal
+ *   exists for. `status` keeps the live registry fallback: it is an
+ *   interactive command where a few seconds for a fresh answer is fine.
+ */
+import { type DaemonMeta } from '../shell/daemon-process.js';
+import { type VersionCheckResult } from '../update/version-check.js';
+import type { InstallMode } from '../update/self-update.js';
+export interface StalenessInfo {
+    /** Version of the running daemon (from daemon.meta.json). */
+    runningVersion: string;
+    /** Latest published version (registry or fresh cache). */
+    latestVersion: string;
+    /** True when latestVersion is strictly newer than runningVersion. */
+    updateAvailable: boolean;
+    /** Install mode of the running daemon, when stamped. */
+    installMode?: InstallMode;
+    /** Whether the running daemon has auto-update enabled, when stamped. */
+    autoUpdateEnabled?: boolean;
+}
+/** On-disk shape of the version-check cache file. */
+export interface VersionCheckCache {
+    checkedAt: string;
+    latestVersion: string;
+}
+/** Cache freshness window. Within this, no network call is made. */
+export declare const VERSION_CHECK_CACHE_TTL_MS: number;
+/** Cache file name within the global state dir (~/.telora/). */
+export declare const VERSION_CHECK_CACHE_FILE = "version-check-cache.json";
+/** Injectable dependencies for {@link getStalenessInfoCore} (tests). */
+export interface StalenessDeps {
+    readMeta: () => DaemonMeta | null;
+    isDaemonRunning: () => boolean;
+    readCache: () => VersionCheckCache | null;
+    writeCache: (cache: VersionCheckCache) => void;
+    checkForUpdates: (currentVersion: string) => Promise<VersionCheckResult | null>;
+    now?: () => number;
+}
+export declare function resolveVersionCheckCachePath(): string;
+/**
+ * Read the version-check cache only when it is FRESH (within the TTL).
+ *
+ * The running daemon keeps this cache warm via {@link startVersionCacheRefreshLoop};
+ * the auto-update controller reads the candidate version from here instead of
+ * issuing a registry call on every idle edge, so rapid idle flapping cannot
+ * produce a registry-call storm. An expired cache returns null -- a stale
+ * answer must never drive an update decision.
+ */
+export declare function readFreshVersionCache(now?: () => number): VersionCheckCache | null;
+/** Options for {@link getStalenessInfoCore} / {@link getStalenessInfo}. */
+export interface StalenessOptions {
+    /**
+     * Never touch the network: answer from a fresh cache or return null.
+     * Used by session-state, whose stdout the SessionStart hook blocks on --
+     * an unreachable registry must not add even one fetch-timeout of latency.
+     * The running daemon's refresh loop keeps the cache warm.
+     */
+    cacheOnly?: boolean;
+}
+/**
+ * Compute staleness info for the running daemon, with injected dependencies.
+ *
+ * Returns null whenever the signal cannot be established with confidence:
+ * no meta file, legacy meta without a version stamp, daemon not running,
+ * or no fresh latest-version answer (expired cache + failed registry check,
+ * or expired cache in cacheOnly mode).
+ */
+export declare function getStalenessInfoCore(deps: StalenessDeps, opts?: StalenessOptions): Promise<StalenessInfo | null>;
+/**
+ * Compute staleness info for the running daemon (production deps).
+ * Never throws; never writes stdout. Returns null when no signal applies.
+ */
+export declare function getStalenessInfo(opts?: StalenessOptions): Promise<StalenessInfo | null>;
+/** Injectable dependencies for {@link maybeRefreshVersionCheckCacheCore} (tests). */
+export interface CacheRefreshDeps {
+    readCache: () => VersionCheckCache | null;
+    writeCache: (cache: VersionCheckCache) => void;
+    checkForUpdates: (currentVersion: string) => Promise<VersionCheckResult | null>;
+    now?: () => number;
+}
+/**
+ * Refresh the version-check cache when it is missing or expired.
+ * Returns true when a fresh registry answer was written, false when the
+ * cache was already fresh or the registry was unreachable (no write -- an
+ * expired cache stays expired rather than being re-stamped with old data).
+ */
+export declare function maybeRefreshVersionCheckCacheCore(deps: CacheRefreshDeps, currentVersion: string): Promise<boolean>;
+/** Production wrapper for {@link maybeRefreshVersionCheckCacheCore}. Never throws. */
+export declare function maybeRefreshVersionCheckCache(currentVersion: string): Promise<boolean>;
+/** Default interval for the daemon-side cache refresh loop (1h, like auto-update). */
+export declare const VERSION_CACHE_REFRESH_INTERVAL_MS: number;
+/**
+ * Start the daemon-side version-cache refresh loop.
+ *
+ * Runs in EVERY install mode regardless of the auto-update flag -- npx with
+ * auto-update disabled is precisely the configuration the staleness signal
+ * exists for. Each tick refreshes the cache only when it is missing/expired
+ * (the TTL throttles registry traffic to ~one fetch per 6h). The unref'd
+ * timer never blocks process exit. Returns a cleanup function.
+ */
+export declare function startVersionCacheRefreshLoop(currentVersion: string, intervalMs?: number): () => void;
+/**
+ * Format the one-line staleness warning, or null when no warning applies.
+ *
+ * When the daemon runs from an npx cache with auto-update disabled, the line
+ * carries the explicit escape hatch: self-update cannot replace an npx-cached
+ * binary in place, so a global install + restart is the fix.
+ */
+export declare function formatStalenessWarning(info: StalenessInfo | null): string | null;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/drift/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../src/drift/staleness.ts"],"names":[],"mappings":"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"}

package/dist/drift/staleness.js

@@ -0,0 +1,249 @@
+/**
+ * Staleness signal: is the RUNNING daemon behind the latest published release?
+ *
+ * Consumed by `telora-daemon status` and `telora-daemon session-state` to
+ * surface a one-line warning when the running daemon version is behind the
+ * latest published @telora/daemon. The CLI binary executing those commands may
+ * be a DIFFERENT install than the running daemon (repo checkout vs npx cache),
+ * so the running version comes from daemon.meta.json -- stamped by the daemon
+ * itself at startup -- never from the CLI's own package.json.
+ *
+ * Design constraints:
+ * - Silent degradation: never writes to stdout; any failure (no meta, legacy
+ *   meta without a version stamp, daemon not running, registry unreachable)
+ *   returns null so callers print their normal output unchanged. The
+ *   underlying checkForUpdates console.warns on failure -- that goes to
+ *   stderr, which the session-state stdout contract tolerates.
+ * - Cached: the registry answer is cached in the global state dir
+ *   (version-check-cache.json) with a 6h TTL. An EXPIRED cache is never used
+ *   as a fallback -- a failed refresh returns null rather than reporting
+ *   staleness from old data (no stale-cache false positives).
+ * - Latency split: session-state is CACHE-ONLY (zero network -- the
+ *   SessionStart hook blocks Claude Code on this command, and an unreachable
+ *   registry would otherwise hang it for the full fetch timeout). The async
+ *   half of "async or cached" lives in the RUNNING DAEMON, which refreshes
+ *   the cache on a timer (startVersionCacheRefreshLoop) in every install
+ *   mode, including npx with auto-update disabled -- the case the signal
+ *   exists for. `status` keeps the live registry fallback: it is an
+ *   interactive command where a few seconds for a fresh answer is fine.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureGlobalStateDir, getDaemonStatus, readDaemonMeta, resolveGlobalStateDir, } from '../shell/daemon-process.js';
+import { checkForUpdates, isNewerVersion } from '../update/version-check.js';
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'staleness' });
+/** Cache freshness window. Within this, no network call is made. */
+export const VERSION_CHECK_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+/** Cache file name within the global state dir (~/.telora/). */
+export const VERSION_CHECK_CACHE_FILE = 'version-check-cache.json';
+// ---------------------------------------------------------------------------
+// Cache file helpers (default deps)
+// ---------------------------------------------------------------------------
+export function resolveVersionCheckCachePath() {
+    return join(resolveGlobalStateDir(), VERSION_CHECK_CACHE_FILE);
+}
+/**
+ * Read the version-check cache only when it is FRESH (within the TTL).
+ *
+ * The running daemon keeps this cache warm via {@link startVersionCacheRefreshLoop};
+ * the auto-update controller reads the candidate version from here instead of
+ * issuing a registry call on every idle edge, so rapid idle flapping cannot
+ * produce a registry-call storm. An expired cache returns null -- a stale
+ * answer must never drive an update decision.
+ */
+export function readFreshVersionCache(now = Date.now) {
+    const cache = readCacheFile();
+    if (!cache)
+        return null;
+    const checkedAtMs = Date.parse(cache.checkedAt);
+    if (!Number.isFinite(checkedAtMs))
+        return null;
+    if (now() - checkedAtMs >= VERSION_CHECK_CACHE_TTL_MS)
+        return null;
+    return cache;
+}
+function readCacheFile() {
+    const path = resolveVersionCheckCachePath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (typeof parsed.checkedAt !== 'string' || typeof parsed.latestVersion !== 'string') {
+            return null;
+        }
+        return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCacheFile(cache) {
+    try {
+        ensureGlobalStateDir();
+        writeFileSync(resolveVersionCheckCachePath(), JSON.stringify(cache, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch (err) {
+        // Best-effort cache: an unwritable state dir must not break the signal.
+        log.debug('Best-effort cache: an unwritable state dir must not break the signal', { error: String(err?.message ?? err) });
+    }
+}
+/**
+ * Compute staleness info for the running daemon, with injected dependencies.
+ *
+ * Returns null whenever the signal cannot be established with confidence:
+ * no meta file, legacy meta without a version stamp, daemon not running,
+ * or no fresh latest-version answer (expired cache + failed registry check,
+ * or expired cache in cacheOnly mode).
+ */
+export async function getStalenessInfoCore(deps, opts = {}) {
+    const meta = deps.readMeta();
+    if (!meta || typeof meta.version !== 'string' || meta.version.length === 0)
+        return null;
+    if (!deps.isDaemonRunning())
+        return null;
+    const runningVersion = meta.version;
+    // Resolve the latest published version: fresh cache first, registry second.
+    let latestVersion = null;
+    const cache = deps.readCache();
+    if (cache) {
+        const checkedAtMs = Date.parse(cache.checkedAt);
+        if (Number.isFinite(checkedAtMs) && (deps.now ?? Date.now)() - checkedAtMs < VERSION_CHECK_CACHE_TTL_MS) {
+            latestVersion = cache.latestVersion;
+        }
+    }
+    if (latestVersion === null) {
+        if (opts.cacheOnly)
+            return null; // No fresh cache and no network allowed -- silent.
+        const result = await deps.checkForUpdates(runningVersion);
+        if (!result)
+            return null; // Registry unreachable -- silent, no stale-cache fallback.
+        latestVersion = result.latestVersion;
+        deps.writeCache({
+            checkedAt: new Date((deps.now ?? Date.now)()).toISOString(),
+            latestVersion,
+        });
+    }
+    return {
+        runningVersion,
+        latestVersion,
+        updateAvailable: isNewerVersion(latestVersion, runningVersion),
+        ...(meta.installMode !== undefined ? { installMode: meta.installMode } : {}),
+        ...(meta.autoUpdateEnabled !== undefined ? { autoUpdateEnabled: meta.autoUpdateEnabled } : {}),
+    };
+}
+/**
+ * Compute staleness info for the running daemon (production deps).
+ * Never throws; never writes stdout. Returns null when no signal applies.
+ */
+export async function getStalenessInfo(opts = {}) {
+    try {
+        return await getStalenessInfoCore({
+            readMeta: readDaemonMeta,
+            isDaemonRunning: () => getDaemonStatus().running,
+            readCache: readCacheFile,
+            writeCache: writeCacheFile,
+            checkForUpdates,
+            now: Date.now,
+        }, opts);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Refresh the version-check cache when it is missing or expired.
+ * Returns true when a fresh registry answer was written, false when the
+ * cache was already fresh or the registry was unreachable (no write -- an
+ * expired cache stays expired rather than being re-stamped with old data).
+ */
+export async function maybeRefreshVersionCheckCacheCore(deps, currentVersion) {
+    const cache = deps.readCache();
+    if (cache) {
+        const checkedAtMs = Date.parse(cache.checkedAt);
+        const withinTtl = Number.isFinite(checkedAtMs) && (deps.now ?? Date.now)() - checkedAtMs < VERSION_CHECK_CACHE_TTL_MS;
+        // A cache entry whose latestVersion is at/below the running version carries
+        // zero actionable signal. After a self-update restart the running version can
+        // leapfrog the cached latest (e.g. running 0.17.53 > cached 0.17.48); the TTL
+        // would otherwise keep that semantically-dead entry authoritative for up to 6h,
+        // blinding the daemon to every subsequently-published release. Force a refresh
+        // in the leapfrog case regardless of cache age -- the startup prime tick then
+        // self-heals the cache on the next boot. The equal case (latest == running, the
+        // up-to-date steady state) still honors the TTL, so registry traffic does not
+        // increase for daemons that are already current.
+        const leapfrogged = isNewerVersion(currentVersion, cache.latestVersion);
+        if (withinTtl && !leapfrogged) {
+            return false; // Fresh and actionable -- nothing to do.
+        }
+    }
+    const result = await deps.checkForUpdates(currentVersion);
+    if (!result)
+        return false;
+    deps.writeCache({
+        checkedAt: new Date((deps.now ?? Date.now)()).toISOString(),
+        latestVersion: result.latestVersion,
+    });
+    return true;
+}
+/** Production wrapper for {@link maybeRefreshVersionCheckCacheCore}. Never throws. */
+export async function maybeRefreshVersionCheckCache(currentVersion) {
+    try {
+        return await maybeRefreshVersionCheckCacheCore({
+            readCache: readCacheFile,
+            writeCache: writeCacheFile,
+            checkForUpdates,
+            now: Date.now,
+        }, currentVersion);
+    }
+    catch {
+        return false;
+    }
+}
+/** Default interval for the daemon-side cache refresh loop (1h, like auto-update). */
+export const VERSION_CACHE_REFRESH_INTERVAL_MS = 60 * 60 * 1000;
+/**
+ * Start the daemon-side version-cache refresh loop.
+ *
+ * Runs in EVERY install mode regardless of the auto-update flag -- npx with
+ * auto-update disabled is precisely the configuration the staleness signal
+ * exists for. Each tick refreshes the cache only when it is missing/expired
+ * (the TTL throttles registry traffic to ~one fetch per 6h). The unref'd
+ * timer never blocks process exit. Returns a cleanup function.
+ */
+export function startVersionCacheRefreshLoop(currentVersion, intervalMs = VERSION_CACHE_REFRESH_INTERVAL_MS) {
+    let stopped = false;
+    const tick = () => {
+        if (stopped)
+            return;
+        void maybeRefreshVersionCheckCache(currentVersion);
+    };
+    tick(); // Prime at startup so the first session-state of the day has data.
+    const timer = setInterval(tick, intervalMs);
+    timer.unref();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}
+// ---------------------------------------------------------------------------
+// Warning-line formatting (shared by status + session-state)
+// ---------------------------------------------------------------------------
+/**
+ * Format the one-line staleness warning, or null when no warning applies.
+ *
+ * When the daemon runs from an npx cache with auto-update disabled, the line
+ * carries the explicit escape hatch: self-update cannot replace an npx-cached
+ * binary in place, so a global install + restart is the fix.
+ */
+export function formatStalenessWarning(info) {
+    if (!info || !info.updateAvailable)
+        return null;
+    let line = `Update available: v${info.runningVersion} running, v${info.latestVersion} published.`;
+    if (info.installMode === 'npx' && info.autoUpdateEnabled === false) {
+        line +=
+            ' Daemon runs from an npx cache with auto-update disabled; self-update cannot replace an npx-cached binary.' +
+                ' Install globally (npm install -g @telora/daemon) and run `telora-daemon restart`.';
+    }
+    return line;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/drift/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../../src/drift/staleness.ts"],"names":[],"mappings":"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"}

package/dist/focus/focus-branch-ahead.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Landed-work check for focus completion.
+ *
+ * A focus reads complete only when its agent work has measurably LANDED where a
+ * human inspecting the tree will find it. The observed failure: an agent branch
+ * carried four substantive commits, was never merged, and the board still read
+ * complete because completion was inferred from delivery status, not from where
+ * the work actually landed.
+ *
+ * This reads branch state DETERMINISTICALLY from git (a standing daemon
+ * invariant -- never inferred from agent claims): true when the focus's agent
+ * branch carries commits not reachable from the product's integration branch.
+ * The focus-completion evaluate phase consults it and holds `complete` open while
+ * the branch is ahead; the merge-back loop lands the branch (the normal outcome)
+ * and files a stuck_focus_branch escalation for a genuinely-unmergeable one.
+ *
+ * @module focus-branch-ahead
+ */
+import { getAllFocusWorktrees } from './focus-worktree-state.js';
+import { branchHasUnmergedCommits } from '../worktree/index.js';
+import type { DaemonConfig } from '../types/index.js';
+/** Injected seam so the check is unit-testable without a real worktree/git. */
+export interface FocusBranchAheadDeps {
+    getAllFocusWorktrees: typeof getAllFocusWorktrees;
+    branchHasUnmergedCommits: typeof branchHasUnmergedCommits;
+}
+/**
+ * True when the focus's agent branch carries commits not reachable from the
+ * product's integration branch -- i.e. its work has NOT landed.
+ *
+ * `productConfig` must be product-SCOPED (configForProduct) so integrationBranch
+ * and repoPath resolve to the focus's own product in a multi-product daemon.
+ *
+ * Returns false when the focus has no tracked worktree (nothing to land). The
+ * git primitive returns false on any git failure rather than throwing, so a git
+ * hiccup fails OPEN (allows complete) rather than wedging completion forever --
+ * the merge-back loop's stuck_focus_branch escalation is the durable backstop
+ * for work that genuinely cannot land, and the evaluate phase re-checks every
+ * tick so a transient false-open self-corrects.
+ */
+export declare function focusBranchAhead(focusId: string, productConfig: DaemonConfig, deps?: FocusBranchAheadDeps): boolean;
+//# sourceMappingURL=focus-branch-ahead.d.ts.map

package/dist/focus/focus-branch-ahead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-branch-ahead.d.ts","sourceRoot":"","sources":["../../src/focus/focus-branch-ahead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;CAC3D;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,YAAY,EAC3B,IAAI,GAAE,oBAAkC,GACvC,OAAO,CAQT"}

package/dist/focus/focus-branch-ahead.js

@@ -0,0 +1,45 @@
+/**
+ * Landed-work check for focus completion.
+ *
+ * A focus reads complete only when its agent work has measurably LANDED where a
+ * human inspecting the tree will find it. The observed failure: an agent branch
+ * carried four substantive commits, was never merged, and the board still read
+ * complete because completion was inferred from delivery status, not from where
+ * the work actually landed.
+ *
+ * This reads branch state DETERMINISTICALLY from git (a standing daemon
+ * invariant -- never inferred from agent claims): true when the focus's agent
+ * branch carries commits not reachable from the product's integration branch.
+ * The focus-completion evaluate phase consults it and holds `complete` open while
+ * the branch is ahead; the merge-back loop lands the branch (the normal outcome)
+ * and files a stuck_focus_branch escalation for a genuinely-unmergeable one.
+ *
+ * @module focus-branch-ahead
+ */
+import { getAllFocusWorktrees } from './focus-worktree-state.js';
+import { branchHasUnmergedCommits } from '../worktree/index.js';
+const defaultDeps = {
+    getAllFocusWorktrees,
+    branchHasUnmergedCommits,
+};
+/**
+ * True when the focus's agent branch carries commits not reachable from the
+ * product's integration branch -- i.e. its work has NOT landed.
+ *
+ * `productConfig` must be product-SCOPED (configForProduct) so integrationBranch
+ * and repoPath resolve to the focus's own product in a multi-product daemon.
+ *
+ * Returns false when the focus has no tracked worktree (nothing to land). The
+ * git primitive returns false on any git failure rather than throwing, so a git
+ * hiccup fails OPEN (allows complete) rather than wedging completion forever --
+ * the merge-back loop's stuck_focus_branch escalation is the durable backstop
+ * for work that genuinely cannot land, and the evaluate phase re-checks every
+ * tick so a transient false-open self-corrects.
+ */
+export function focusBranchAhead(focusId, productConfig, deps = defaultDeps) {
+    const wt = deps.getAllFocusWorktrees().get(focusId);
+    if (!wt)
+        return false;
+    return deps.branchHasUnmergedCommits(wt.branchName, productConfig.integrationBranch, productConfig.repoPath);
+}
+//# sourceMappingURL=focus-branch-ahead.js.map

package/dist/focus/focus-branch-ahead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-branch-ahead.js","sourceRoot":"","sources":["../../src/focus/focus-branch-ahead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAShE,MAAM,WAAW,GAAyB;IACxC,oBAAoB;IACpB,wBAAwB;CACzB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,aAA2B,EAC3B,OAA6B,WAAW;IAExC,MAAM,EAAE,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IACtB,OAAO,IAAI,CAAC,wBAAwB,CAClC,EAAE,CAAC,UAAU,EACb,aAAa,CAAC,iBAAiB,EAC/B,aAAa,CAAC,QAAQ,CACvB,CAAC;AACJ,CAAC"}

package/dist/focus/focus-branch-identity.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Focus branch identity: derivation, pinning, and worktree-dir mapping.
+ *
+ * A focus's branch name was historically re-derived from the LIVE agent-role
+ * registry at every spawn (generateFocusBranchName below). A mid-flight role
+ * rename/reassignment therefore changed which branch the daemon's git plumbing
+ * addressed -- pointing spawns, review-coverage rev-parse, and worktree
+ * resolution at a branch that never existed (the 2026-08-06 Tinker Tailor
+ * incident).
+ *
+ * The identity is now PINNED: persisted (product_focuses.branch_name) the first
+ * time the focus branch is created, and read back thereafter. resolveFocusBranchName
+ * is the single decision point -- read the pinned value if present, otherwise
+ * derive it (and signal the caller to persist it, write-once).
+ *
+ * Extracted into its own light module (only a type import + sanitizeGitSegment,
+ * NO @telora/daemon-core / spawn graph) so every consumer -- spawn, lifecycle,
+ * provisioning, worktree resolution -- and the unit tests can use it without
+ * pulling in focus-executor.ts. focus-executor re-exports generateFocusBranchName
+ * for back-compat with existing importers.
+ */
+import type { AgentRole } from '../types/index.js';
+/**
+ * Derive the focus branch name from the role, focus name, and focus id:
+ * `agent/<role>/<focus-name>-<short-id>`. This is the FIRST-CREATION deriver
+ * only -- once a focus has a pinned branch_name, consumers read that instead
+ * (see resolveFocusBranchName). The short-id is the immutable focus-id prefix.
+ */
+export declare function generateFocusBranchName(role: AgentRole, focusName: string, focusId: string): string;
+/**
+ * Map a focus branch name to its worktree directory name. The worktree path is
+ * `join(worktreeDir, branchName.replace('/', '-'))` (worktree.ts), so a pinned
+ * branch name pins the worktree directory too -- one stored value covers both.
+ */
+export declare function focusWorktreeDirName(branchName: string): string;
+/** Result of resolving a focus's branch identity. */
+export interface ResolvedFocusBranch {
+    /** The branch name to use for all git plumbing this spawn. */
+    branchName: string;
+    /**
+     * True when `branchName` came from the persisted pin. False when it was
+     * freshly derived because no pin existed yet -- the caller should persist it
+     * (setFocusBranchName) so the identity is captured on first creation.
+     */
+    pinned: boolean;
+}
+/**
+ * Resolve a focus's branch identity, preferring the pinned value.
+ *
+ * If `pinnedBranch` is a non-empty string, it is returned verbatim (immune to
+ * role renames -- this is the whole point). Otherwise the name is derived from
+ * the current role and `pinned:false` signals the caller to persist it. A
+ * blank/whitespace pinned value is treated as absent (defensive against an
+ * empty column write).
+ */
+export declare function resolveFocusBranchName(args: {
+    pinnedBranch: string | null | undefined;
+    role: AgentRole;
+    focusName: string;
+    focusId: string;
+}): ResolvedFocusBranch;
+//# sourceMappingURL=focus-branch-identity.d.ts.map

package/dist/focus/focus-branch-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-branch-identity.d.ts","sourceRoot":"","sources":["../../src/focus/focus-branch-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKnG;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,mBAAmB,CAMtB"}

package/dist/focus/focus-branch-identity.js

@@ -0,0 +1,59 @@
+/**
+ * Focus branch identity: derivation, pinning, and worktree-dir mapping.
+ *
+ * A focus's branch name was historically re-derived from the LIVE agent-role
+ * registry at every spawn (generateFocusBranchName below). A mid-flight role
+ * rename/reassignment therefore changed which branch the daemon's git plumbing
+ * addressed -- pointing spawns, review-coverage rev-parse, and worktree
+ * resolution at a branch that never existed (the 2026-08-06 Tinker Tailor
+ * incident).
+ *
+ * The identity is now PINNED: persisted (product_focuses.branch_name) the first
+ * time the focus branch is created, and read back thereafter. resolveFocusBranchName
+ * is the single decision point -- read the pinned value if present, otherwise
+ * derive it (and signal the caller to persist it, write-once).
+ *
+ * Extracted into its own light module (only a type import + sanitizeGitSegment,
+ * NO @telora/daemon-core / spawn graph) so every consumer -- spawn, lifecycle,
+ * provisioning, worktree resolution -- and the unit tests can use it without
+ * pulling in focus-executor.ts. focus-executor re-exports generateFocusBranchName
+ * for back-compat with existing importers.
+ */
+import { sanitizeGitSegment } from '../git/utils.js';
+/**
+ * Derive the focus branch name from the role, focus name, and focus id:
+ * `agent/<role>/<focus-name>-<short-id>`. This is the FIRST-CREATION deriver
+ * only -- once a focus has a pinned branch_name, consumers read that instead
+ * (see resolveFocusBranchName). The short-id is the immutable focus-id prefix.
+ */
+export function generateFocusBranchName(role, focusName, focusId) {
+    const sanitizedRoleName = sanitizeGitSegment(role.name);
+    const shortId = focusId.slice(0, 8);
+    const sanitizedFocusName = sanitizeGitSegment(focusName);
+    return `agent/${sanitizedRoleName}/${sanitizedFocusName}-${shortId}`;
+}
+/**
+ * Map a focus branch name to its worktree directory name. The worktree path is
+ * `join(worktreeDir, branchName.replace('/', '-'))` (worktree.ts), so a pinned
+ * branch name pins the worktree directory too -- one stored value covers both.
+ */
+export function focusWorktreeDirName(branchName) {
+    return branchName.replace(/\//g, '-');
+}
+/**
+ * Resolve a focus's branch identity, preferring the pinned value.
+ *
+ * If `pinnedBranch` is a non-empty string, it is returned verbatim (immune to
+ * role renames -- this is the whole point). Otherwise the name is derived from
+ * the current role and `pinned:false` signals the caller to persist it. A
+ * blank/whitespace pinned value is treated as absent (defensive against an
+ * empty column write).
+ */
+export function resolveFocusBranchName(args) {
+    const { pinnedBranch, role, focusName, focusId } = args;
+    if (typeof pinnedBranch === 'string' && pinnedBranch.trim().length > 0) {
+        return { branchName: pinnedBranch, pinned: true };
+    }
+    return { branchName: generateFocusBranchName(role, focusName, focusId), pinned: false };
+}
+//# sourceMappingURL=focus-branch-identity.js.map

package/dist/focus/focus-branch-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-branch-identity.js","sourceRoot":"","sources":["../../src/focus/focus-branch-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAe,EAAE,SAAiB,EAAE,OAAe;IACzF,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACzD,OAAO,SAAS,iBAAiB,IAAI,kBAAkB,IAAI,OAAO,EAAE,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAKtC;IACC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACxD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,uBAAuB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC1F,CAAC"}