@telora/daemon 0.21.26 → 0.21.82

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"}

package/dist/focus/focus-engine.d.ts

@@ -0,0 +1,74 @@
+/**
+ * FocusEngine -- ExecutionEngine adapter for the focus-based daemon.
+ *
+ * Wraps the existing daemon modules (listener, heartbeat, spawner, git, etc.)
+ * behind the ExecutionEngine interface from @telora/daemon-core. This allows
+ * the unified process shell to manage the focus engine without knowing
+ * its internals.
+ *
+ * Lifecycle (called by the process shell):
+ *   1. init(config)           -- validate, connect to Supabase, init git
+ *   2. recoverFromCrash()     -- reconcile orphaned state from previous run
+ *   3. start()                -- begin polling loops and heartbeat
+ *   4. stop()                 -- stop accepting new work
+ *   5. shutdown()             -- graceful cleanup (kill teams, WIP commit, drain)
+ */
+import type { ExecutionEngine, EngineHealth, ResourceUsage, BaseConfig } from '@telora/daemon-core';
+import { ResourceGovernor } from '@telora/daemon-core';
+import type { DaemonConfig } from '../types/index.js';
+/**
+ * Decide whether a loop tick should be enabled based on an environment
+ * variable. Opt-out semantics:
+ *
+ *   unset       -> true   (NEW default: loop fires)
+ *   ''          -> true   (treated like unset)
+ *   '0'         -> false  (explicit opt-out)
+ *   anything    -> true   ('1', 'true', 'yes', etc.)
+ *
+ * Operators disable the loop by setting the env var to '0' (in
+ * `.telora/daemon.json`'s `env` block or as a process env var) and
+ * restarting the daemon. See `docs/runbook-loop-activation.md`.
+ *
+ * @param envVarName Name of the process.env variable (e.g. TELORA_FOCUS_LOOP).
+ * @param env Optional env source for testing; defaults to process.env.
+ */
+export declare function shouldRunLoop(envVarName: string, env?: NodeJS.ProcessEnv): boolean;
+export declare class FocusEngine implements ExecutionEngine {
+    readonly name = "focus";
+    /** Daemon config, set during init(). */
+    private config;
+    /**
+     * Optional resource governor for global concurrency limiting.
+     * Non-private so LOOP_REGISTRY descriptors (focus-loop-registry.ts) can read
+     * it via the structural LoopEngineHost surface.
+     */
+    governor: ResourceGovernor | null;
+    /**
+     * Interval handles for periodic tasks (cleared in stop/shutdown).
+     * Non-private so LOOP_REGISTRY descriptors push their safeInterval handles
+     * here via the structural LoopEngineHost surface.
+     */
+    intervals: ReturnType<typeof setInterval>[];
+    /** Last scanned timestamp for git activity per product (reset on restart). */
+    private lastGitScanTimestamps;
+    /**
+     * Inject a ResourceGovernor for global concurrency limiting.
+     * Called by the process shell after construction but before start().
+     */
+    setGovernor(gov: ResourceGovernor): void;
+    init(config: BaseConfig & Record<string, unknown>): Promise<void>;
+    recoverFromCrash(): Promise<void>;
+    start(): Promise<void>;
+    tickFocusLoop(config: DaemonConfig): Promise<void>;
+    private scanAndUpsertGitActivity;
+    stop(): void;
+    shutdown(): Promise<void>;
+    healthCheck(): EngineHealth;
+    getResourceUsage(): ResourceUsage;
+    /**
+     * Assert that config has been set (init() was called) and return it.
+     * Throws a clear error if called before init().
+     */
+    private requireConfig;
+}
+//# sourceMappingURL=focus-engine.d.ts.map

package/dist/focus/focus-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-engine.d.ts","sourceRoot":"","sources":["../../src/focus/focus-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,UAAU,EACX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAA2B,gBAAgB,EAAoC,MAAM,qBAAqB,CAAC;AAClH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA0DtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAOT;AAMD,qBAAa,WAAY,YAAW,eAAe;IACjD,QAAQ,CAAC,IAAI,WAAW;IAExB,wCAAwC;IACxC,OAAO,CAAC,MAAM,CAA6B;IAE3C;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IAEzC;;;;OAIG;IACH,SAAS,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,EAAE,CAAM;IAEjD,8EAA8E;IAC9E,OAAO,CAAC,qBAAqB,CAA6B;IAE1D;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI;IAUlC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkEjE,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAsEjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2FtB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAiE1C,wBAAwB;IA+BtC,IAAI,IAAI,IAAI;IAeN,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA+F/B,WAAW,IAAI,YAAY;IA8C3B,gBAAgB,IAAI,aAAa;IAsBjC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAStB"}