@fluado/enmetu 0.0.0-stage → 0.1.0

package/dist/core/state/stateRecordStep.js

@@ -0,0 +1,203 @@
+/** The hard maximum of stateHistory: a typo or a library caller cannot make state.json large. */
+export const MAX_STATE_HISTORY = 100;
+/**
+ * A longer message (a halt's) is cut to this many characters and ends in
+ * "...". Characters are code points (Array.from), so an astral character is
+ * never split into a lone surrogate.
+ */
+export const MAX_STATE_MESSAGE_CHARACTERS = 300;
+/**
+ * How many orphaned commits the record keeps, newest last (design 14.15). An
+ * orphan needs a person's commit inside enmetu's stopped rebase, so five
+ * pending at once is already far beyond what the window produces; the cap
+ * keeps state.json bounded (Decision 63) whatever happens.
+ */
+export const MAX_ORPHANED_COMMITS = 5;
+/** An orphaned commit's subject is cut to this many characters, like a message (git's conventional subject width). */
+export const MAX_ORPHAN_SUBJECT_CHARACTERS = 72;
+const ELLIPSIS = '...';
+/**
+ * The base of an event that arrives without a started record. Its instance
+ * matches no lock holder (pid 0), so liveness never takes it for a live one.
+ */
+const EMPTY_RECORD = {
+    version: 1,
+    instance: { pid: 0, hostname: '', startedAt: '' },
+    state: 'starting',
+    reason: null,
+    message: '',
+    since: '',
+    pushed: null,
+    unpushed: null,
+    lastCycle: null,
+    conflict: null,
+    history: [],
+    orphaned: [],
+};
+/**
+ * Functional core of the state record (design 12.1): the record after an
+ * event. A transition is a change of (state, reason); it moves `since` and is
+ * appended to the history, which keeps the newest min(historyCap,
+ * MAX_STATE_HISTORY) entries. `started` begins a fresh record for the new
+ * instance and carries the previous history across the restart; any other
+ * event without a previous record applies to EMPTY_RECORD.
+ */
+export function stateRecordStep(previous, event, at, historyCap) {
+    const cap = Math.max(0, Math.min(historyCap, MAX_STATE_HISTORY));
+    switch (event.type) {
+        case 'started':
+            return {
+                version: 1,
+                instance: {
+                    pid: event.instance.pid,
+                    hostname: event.instance.hostname,
+                    startedAt: event.instance.startedAt,
+                },
+                state: 'starting',
+                reason: null,
+                message: 'started; the first cycle has not finished',
+                since: at,
+                pushed: null,
+                unpushed: null,
+                lastCycle: null,
+                conflict: null,
+                history: appendTransition(previous?.history ?? [], { state: 'starting', reason: null, at }, cap),
+                // An orphaned commit stays on no branch across a restart.
+                orphaned: previous?.orphaned ?? [],
+            };
+        case 'cycleFinished': {
+            const base = previous ?? EMPTY_RECORD;
+            const part = outcomePart(event.outcome);
+            return {
+                ...withPart(base, part, at, cap),
+                pushed: event.upstream.pushed,
+                unpushed: event.upstream.unpushed,
+                lastCycle: { cycleId: event.cycleId, outcome: event.outcome.kind, at },
+                conflict: event.outcome.kind === 'conflict' ? event.conflict : null,
+            };
+        }
+        case 'cycleFailed': {
+            // A throw says nothing about whether the state or its reason ended, as
+            // in SyncCycleRunner; only the heartbeat moves.
+            const base = previous ?? EMPTY_RECORD;
+            return {
+                ...base,
+                lastCycle: { cycleId: event.cycleId, outcome: 'failed', at },
+            };
+        }
+        case 'halted':
+            return withPart(previous ?? EMPTY_RECORD, { state: 'halted', reason: event.code, message: event.message }, at, cap);
+        case 'stopped':
+            return withPart(previous ?? EMPTY_RECORD, { state: 'stopped', reason: null, message: event.message }, at, cap);
+        case 'commitOrphaned': {
+            // Not a transition: the cycle that orphaned it reports its own outcome.
+            const base = previous ?? EMPTY_RECORD;
+            return {
+                ...base,
+                orphaned: withOrphan(base.orphaned, {
+                    commit: event.commit,
+                    base: event.base,
+                    subject: cutText(event.subject, MAX_ORPHAN_SUBJECT_CHARACTERS),
+                    at,
+                }),
+            };
+        }
+    }
+}
+/**
+ * The list with the orphan appended, the newest MAX_ORPHANED_COMMITS kept. A
+ * commit already listed keeps its first entry: a recovery that names the same
+ * commit again (a crash after the live line) says nothing new.
+ */
+function withOrphan(orphaned, orphan) {
+    if (orphaned.some((entry) => entry.commit === orphan.commit)) {
+        return orphaned;
+    }
+    return [...orphaned, orphan].slice(-MAX_ORPHANED_COMMITS);
+}
+/** The record with a new state part; since and the history move only on a transition. */
+function withPart(base, part, at, cap) {
+    const transition = part.state !== base.state || part.reason !== base.reason;
+    return {
+        ...base,
+        state: part.state,
+        reason: part.reason,
+        message: cutMessage(part.message),
+        since: transition ? at : base.since,
+        history: transition
+            ? appendTransition(base.history, { state: part.state, reason: part.reason, at }, cap)
+            : capHistory(base.history, cap),
+    };
+}
+function outcomePart(outcome) {
+    switch (outcome.kind) {
+        case 'synced':
+            return {
+                state: 'synced',
+                reason: null,
+                message: 'in sync with the upstream',
+            };
+        case 'paused':
+            return {
+                state: 'paused',
+                reason: outcome.reason,
+                message: `paused: ${outcome.reason}`,
+            };
+        case 'waiting':
+            return {
+                state: 'waiting',
+                reason: outcome.reason,
+                message: outcome.reason === 'PARTIAL_SELECTION_STAGED'
+                    ? 'waiting: a partial selection is staged'
+                    : 'waiting: a commit hook rejected the commit',
+            };
+        case 'busy':
+            return {
+                state: 'busy',
+                reason: null,
+                message: 'git is busy in this repository',
+            };
+        case 'offline':
+            return {
+                state: 'offline',
+                reason: null,
+                message: 'the remote is unreachable',
+            };
+        case 'conflict':
+            return {
+                state: 'conflict',
+                reason: null,
+                message: 'conflict held: the rebase onto the upstream stopped; local commits kept',
+            };
+        case 'push-failed':
+            return {
+                state: 'push-failed',
+                reason: null,
+                message: 'the last push failed',
+            };
+        case 'halted':
+            return {
+                state: 'halted',
+                reason: outcome.code,
+                message: `halted: ${outcome.code}`,
+            };
+    }
+}
+function appendTransition(history, transition, cap) {
+    return capHistory([...history, transition], cap);
+}
+/** The newest `cap` entries; also trims a stored history written under a larger cap. */
+function capHistory(history, cap) {
+    return cap === 0 ? [] : history.slice(-cap);
+}
+function cutMessage(message) {
+    return cutText(message, MAX_STATE_MESSAGE_CHARACTERS);
+}
+/** Cut on code points, so the record never holds half of a surrogate pair. */
+function cutText(text, maxCharacters) {
+    const characters = Array.from(text);
+    if (characters.length <= maxCharacters) {
+        return text;
+    }
+    return `${characters.slice(0, maxCharacters - ELLIPSIS.length).join('')}${ELLIPSIS}`;
+}

package/dist/core/status/conflictGuide.d.ts

@@ -0,0 +1,30 @@
+import type { Upstream } from '../../contracts/gitTypes.js';
+import type { ConflictKey } from '../../contracts/syncTypes.js';
+/** At most this many paths are named; the rest are counted. */
+export declare const MAX_GUIDE_PATHS = 20;
+export interface ConflictGuideInput {
+    /** When the record entered the conflict state. */
+    readonly since: string;
+    readonly conflict: ConflictKey;
+    readonly branchRef: string;
+    readonly upstream: Upstream;
+    /** Local commits not on the upstream; null when unknown. */
+    readonly unpushed: number | null;
+    /** pathsOnBothSides of the two sides since their merge base. */
+    readonly paths: readonly string[];
+}
+/** One status line: label '' continues the line above. */
+export interface GuideLine {
+    readonly label: string;
+    readonly value: string;
+}
+/** Paths in the local list that the upstream list also has, in the local order, each once. */
+export declare function pathsOnBothSides(local: readonly string[], upstream: readonly string[]): readonly string[];
+/**
+ * The conflict guide of design 12.3: what is held, which paths, that the
+ * local commits are kept untouched, and the exact commands for each way a
+ * held conflict ends (Decision 49). Every command is plain git a person can
+ * paste; the reset names the full object id, because a short id can become
+ * ambiguous and a reset to the wrong commit discards work.
+ */
+export declare function conflictGuide(input: ConflictGuideInput): readonly GuideLine[];

package/dist/core/status/conflictGuide.js

@@ -0,0 +1,86 @@
+/** At most this many paths are named; the rest are counted. */
+export const MAX_GUIDE_PATHS = 20;
+const BRANCH_PREFIX = 'refs/heads/';
+const SHORT_SHA_LENGTH = 7;
+/** Paths in the local list that the upstream list also has, in the local order, each once. */
+export function pathsOnBothSides(local, upstream) {
+    const theirs = new Set(upstream);
+    const both = new Set();
+    for (const path of local) {
+        if (theirs.has(path)) {
+            both.add(path);
+        }
+    }
+    return Array.from(both);
+}
+/**
+ * The conflict guide of design 12.3: what is held, which paths, that the
+ * local commits are kept untouched, and the exact commands for each way a
+ * held conflict ends (Decision 49). Every command is plain git a person can
+ * paste; the reset names the full object id, because a short id can become
+ * ambiguous and a reset to the wrong commit discards work.
+ */
+export function conflictGuide(input) {
+    const { conflict, upstream } = input;
+    const branch = shortBranch(input.branchRef);
+    const remoteBranch = shortBranch(upstream.remoteRef);
+    const pull = `${upstream.remote} ${remoteBranch}`;
+    return [
+        {
+            label: 'conflict',
+            value: `held since ${input.since}: the rebase of ${shortSha(conflict.head)} onto ${shortSha(conflict.upstream)} (${upstream.remote} ${upstream.remoteRef}) stopped and was undone`,
+        },
+        { label: 'paths', value: describePaths(input.paths, conflict) },
+        {
+            label: 'kept',
+            value: `${describeLocalCommits(input.unpushed)} on ${branch} untouched; none is pushed and nothing is pulled until the conflict ends`,
+        },
+        {
+            label: 'end it',
+            value: '1. wait: when the upstream changes so the replay no longer conflicts, enmetu continues by itself',
+        },
+        {
+            label: '',
+            value: `2. rebase by hand: git pull --rebase ${pull}, resolve, git add <path>, git rebase --continue`,
+        },
+        {
+            label: '',
+            // --no-ff overrides merge.ff=only, which makes `git pull --no-rebase` refuse
+            // a merge of diverged histories (measured with git 2.52; pull.ff=only is
+            // already overridden by --no-rebase). While a conflict is held the
+            // histories have diverged, so the flag changes nothing else.
+            value: `3. merge by hand: git pull --no-rebase --no-ff ${pull}, resolve, git add <path>, git commit`,
+        },
+        {
+            label: '',
+            value: `4. give up the local commits: git reset --hard ${conflict.upstream} (this also discards uncommitted changes; the local commits stay in the reflog until git prunes them)`,
+        },
+    ];
+}
+function describePaths(paths, conflict) {
+    if (paths.length === 0) {
+        // Two commits, not the three-dot form: that one needs a merge base, which
+        // unrelated histories lack (git exits 128), and shows only the upstream side.
+        return `none found; compare them with: git diff ${conflict.head} ${conflict.upstream}`;
+    }
+    const named = paths.slice(0, MAX_GUIDE_PATHS).join(', ');
+    const rest = paths.length - MAX_GUIDE_PATHS;
+    const more = rest > 0 ? ` and ${rest} more` : '';
+    return `${named}${more} (changed on both sides; at least one conflicts)`;
+}
+function describeLocalCommits(unpushed) {
+    if (unpushed === null) {
+        return 'the local commits stay';
+    }
+    if (unpushed === 1) {
+        return '1 local commit stays';
+    }
+    return `${unpushed} local commits stay`;
+}
+// A ref outside refs/heads keeps its full name, which git pull accepts too.
+function shortBranch(ref) {
+    return ref.startsWith(BRANCH_PREFIX) ? ref.slice(BRANCH_PREFIX.length) : ref;
+}
+function shortSha(sha) {
+    return sha.slice(0, SHORT_SHA_LENGTH);
+}

package/dist/core/status/orphanedCommits.d.ts

@@ -0,0 +1,15 @@
+import type { OrphanedCommit } from '../../contracts/IStateStore.js';
+import type { GuideLine } from './conflictGuide.js';
+/**
+ * The command that puts an orphaned commit on the person's branch (design
+ * 14.15). -x records "(cherry picked from commit <id>)" in each new commit,
+ * also after a resolved conflict (measured, git 2.52), which is how status
+ * tells a picked orphan from a pending one: the pick gives it a new id, so
+ * the original never becomes reachable.
+ */
+export declare function orphanRecoveryCommand(orphan: OrphanedCommit): string;
+/**
+ * One `orphaned` line per pending orphan, oldest first (design 14.15), after
+ * the uncommitted line. The full ids stay in the command, so it can be pasted unchanged.
+ */
+export declare function orphanedCommitLines(pending: readonly OrphanedCommit[]): readonly GuideLine[];

package/dist/core/status/orphanedCommits.js

@@ -0,0 +1,24 @@
+const SHORT_SHA_LENGTH = 7;
+/**
+ * The command that puts an orphaned commit on the person's branch (design
+ * 14.15). -x records "(cherry picked from commit <id>)" in each new commit,
+ * also after a resolved conflict (measured, git 2.52), which is how status
+ * tells a picked orphan from a pending one: the pick gives it a new id, so
+ * the original never becomes reachable.
+ */
+export function orphanRecoveryCommand(orphan) {
+    return `git cherry-pick -x ${orphan.base}..${orphan.commit}`;
+}
+/**
+ * One `orphaned` line per pending orphan, oldest first (design 14.15), after
+ * the uncommitted line. The full ids stay in the command, so it can be pasted unchanged.
+ */
+export function orphanedCommitLines(pending) {
+    return pending.map((orphan) => {
+        const subject = orphan.subject === '' ? '' : ` "${orphan.subject}"`;
+        return {
+            label: 'orphaned',
+            value: `${orphan.commit.slice(0, SHORT_SHA_LENGTH)}${subject} is on no branch since ${orphan.at}; ${orphanRecoveryCommand(orphan)} puts it on yours`,
+        };
+    });
+}

package/dist/core/status/statusHeadline.d.ts

@@ -0,0 +1,46 @@
+import type { HaltRecord } from '../../contracts/IHaltStore.js';
+import type { OrphanedCommit, StateRecord } from '../../contracts/IStateStore.js';
+import type { StateLiveness } from '../../contracts/library.js';
+/** Local commits not on the upstream, counted by status from git (never from the record). */
+export type UnpushedFact = {
+    readonly kind: 'counted';
+    readonly ahead: number;
+}
+/** An upstream is configured, but neither its tracking ref nor enmetu's verified ref exists. */
+ | {
+    readonly kind: 'unknown';
+}
+/** Detached HEAD, or a branch without upstream. */
+ | {
+    readonly kind: 'no-upstream';
+};
+export interface HeadlineInput {
+    readonly halt: HaltRecord | null;
+    readonly liveness: StateLiveness;
+    readonly record: StateRecord | null;
+    readonly unpushed: UnpushedFact;
+    /**
+     * Paths git status reports changed or untracked, counted live by status:
+     * edits inside the quiet window, files the content guard excludes, what a
+     * hook rejected or left. Work that exists only on this disk (design 12.2).
+     */
+    readonly uncommitted: number;
+    /**
+     * The recorded orphaned commits git still finds on no local branch, judged
+     * live by status (design 14.15); oldest first.
+     */
+    readonly orphaned: readonly OrphanedCommit[];
+}
+/**
+ * The first line of `enmetu status` (design 12.2): one answer to "is my work
+ * safe and pushed?", starting with one of safe, pending, syncing, waiting,
+ * attention, paused, offline, busy, starting, halted, running or not running.
+ * safe only when nothing is uncommitted and nothing is unpushed.
+ *
+ * The rows of the 12.2 table in order, first match wins, with design 14.15's
+ * orphaned-commit row right after the halt row. stateLiveness never
+ * pairs stopped, crashed or running with a missing record; should a caller do
+ * so anyway, the line falls back to the "no state recorded" rows, which are
+ * true for that input.
+ */
+export declare function statusHeadline(input: HeadlineInput): string;

package/dist/core/status/statusHeadline.js

@@ -0,0 +1,130 @@
+/** `<sha7>` of design 12.2. */
+const SHORT_SHA_LENGTH = 7;
+/**
+ * The first line of `enmetu status` (design 12.2): one answer to "is my work
+ * safe and pushed?", starting with one of safe, pending, syncing, waiting,
+ * attention, paused, offline, busy, starting, halted, running or not running.
+ * safe only when nothing is uncommitted and nothing is unpushed.
+ *
+ * The rows of the 12.2 table in order, first match wins, with design 14.15's
+ * orphaned-commit row right after the halt row. stateLiveness never
+ * pairs stopped, crashed or running with a missing record; should a caller do
+ * so anyway, the line falls back to the "no state recorded" rows, which are
+ * true for that input.
+ */
+export function statusHeadline(input) {
+    const work = workText(input.uncommitted, input.unpushed);
+    if (input.halt !== null) {
+        return `halted: ${input.halt.code} since ${input.halt.at}, ${work}`;
+    }
+    // A commit on no branch is work that is neither committed on the branch nor
+    // pushed, whatever the daemon does now, so it outranks every liveness row;
+    // the instance and state lines still say whether enmetu runs (design 14.15).
+    const oldest = input.orphaned[0];
+    if (oldest !== undefined) {
+        const commits = input.orphaned.length === 1
+            ? '1 commit'
+            : `${input.orphaned.length} commits`;
+        return `attention: ${commits} on no branch since ${oldest.at}, ${work}`;
+    }
+    const record = input.record;
+    switch (input.liveness) {
+        case 'never':
+            return `not running: no state recorded, ${work}`;
+        case 'stopped':
+            return record === null
+                ? `not running: no state recorded, ${work}`
+                : `not running: last state stopped at ${record.since}, ${work}`;
+        case 'crashed':
+            return record === null
+                ? `not running: no state recorded, ${work}`
+                : `not running: last state ${record.state} at ${record.since}; enmetu ended without recording a stop, ${work}`;
+        case 'unrecorded':
+            return `running: no state recorded yet, ${work}`;
+        case 'running':
+            return record === null
+                ? `running: no state recorded yet, ${work}`
+                : runningHeadline(record, input.uncommitted, input.unpushed);
+    }
+}
+function runningHeadline(record, uncommitted, unpushed) {
+    const work = workText(uncommitted, unpushed);
+    const since = record.since;
+    // A throw says nothing about whether the recorded state still holds
+    // (design 12.1), so a failed cycle outranks the state.
+    if (record.lastCycle?.outcome === 'failed') {
+        return `attention: the last cycle failed at ${record.lastCycle.at}, ${work}`;
+    }
+    switch (record.state) {
+        case 'synced':
+            return syncedHeadline(record, uncommitted, unpushed);
+        case 'conflict':
+            return `attention: conflict since ${since}, ${work}`;
+        case 'push-failed':
+            return `attention: pushes failing since ${since}, ${work}`;
+        case 'waiting':
+            if (record.reason === 'PARTIAL_SELECTION_STAGED') {
+                return `waiting: a partial selection is staged since ${since}; nothing is committed or pulled until it is committed or unstaged, ${work}`;
+            }
+            if (record.reason === 'COMMIT_HOOK_REJECTED') {
+                return `waiting: a commit hook rejected the last commit since ${since}, ${work}`;
+            }
+            return `waiting:${reasonText(record)} since ${since}, ${work}`;
+        case 'paused':
+            return `paused:${reasonText(record)} since ${since}, ${work}`;
+        case 'offline':
+            return `offline: since ${since}, ${work}`;
+        case 'busy':
+            return `busy: git is busy since ${since}, ${work}`;
+        case 'starting':
+            return `starting: since ${since}, ${work}`;
+        case 'halted':
+            return `halted:${reasonText(record)} since ${since}, ${work}`;
+        case 'stopped':
+            // stateLiveness judges a stopped record stopped, never running; kept so
+            // every input has a line.
+            return `not running: last state stopped at ${since}, ${work}`;
+    }
+}
+/** safe only at 0 uncommitted and a counted 0 unpushed (Decision 85). */
+function syncedHeadline(record, uncommitted, unpushed) {
+    const pushed = pushedText(record.pushed);
+    if (uncommitted > 0) {
+        return `pending: ${uncommitted} uncommitted, ${unpushedText(unpushed)}, ${pushed}`;
+    }
+    if (unpushed.kind === 'counted' && unpushed.ahead === 0) {
+        return record.pushed === null
+            ? 'safe: 0 unpushed'
+            : `safe: pushed ${shortSha(record.pushed)}, 0 unpushed`;
+    }
+    return `syncing: ${unpushedText(unpushed)}, ${pushed}`;
+}
+/** `<W>`: the uncommitted count first when there is one, then `<U>`. */
+function workText(uncommitted, unpushed) {
+    const counted = unpushedText(unpushed);
+    return uncommitted > 0 ? `${uncommitted} uncommitted, ${counted}` : counted;
+}
+/** `<U>`. */
+function unpushedText(unpushed) {
+    switch (unpushed.kind) {
+        case 'counted':
+            return `${unpushed.ahead} unpushed`;
+        case 'unknown':
+            return 'unpushed unknown';
+        case 'no-upstream':
+            return 'no upstream';
+    }
+}
+/** `<P>`. */
+function pushedText(pushed) {
+    return pushed === null
+        ? 'nothing pushed yet'
+        : `last pushed ${shortSha(pushed)}`;
+}
+/** ` <REASON>`, or nothing for a record that carries none. */
+function reasonText(record) {
+    return record.reason === null ? '' : ` ${record.reason}`;
+}
+function shortSha(sha) {
+    return sha.slice(0, SHORT_SHA_LENGTH);
+}

package/dist/core/watch/watchFilter.d.ts

@@ -0,0 +1,2 @@
+/** filename null (the platform did not say) is a change, never noise. */
+export declare function isWatchNoise(relativePath: string | null): boolean;

package/dist/core/watch/watchFilter.js

@@ -0,0 +1,34 @@
+// Matched against whole path components, so .gitignore, .github/ and
+// node_modules.md are not noise (D8).
+const NOISE_COMPONENTS = new Set(['.git', 'node_modules']);
+const NOISE_BASENAMES = new Set([
+    '.DS_Store',
+    'Thumbs.db',
+    '.Spotlight-V100',
+    '.Trashes',
+    '.fseventsd',
+    // vim creates and deletes this file to probe whether it may write the directory.
+    '4913',
+]);
+const NOISE_BASENAME_PATTERNS = [
+    /\.sw[a-p]$/,
+    /~$/,
+    /^\.#/,
+    /^#.*#$/,
+    /___jb_(tmp|old)___$/,
+    /\.crswap$/,
+    /^\.~lock\..*#$/,
+];
+/** filename null (the platform did not say) is a change, never noise. */
+export function isWatchNoise(relativePath) {
+    if (relativePath === null) {
+        return false;
+    }
+    const components = relativePath.split('/');
+    if (components.some((component) => NOISE_COMPONENTS.has(component))) {
+        return true;
+    }
+    const basename = components[components.length - 1] ?? '';
+    return (NOISE_BASENAMES.has(basename) ||
+        NOISE_BASENAME_PATTERNS.some((pattern) => pattern.test(basename)));
+}

package/dist/daemon/daemon.d.ts

@@ -0,0 +1,55 @@
+import { type ExitCode } from '../contracts/exitCode.js';
+import type { IClock } from '../contracts/IClock.js';
+import type { IDaemon, IPreflight, IRecovery } from '../contracts/IDaemon.js';
+import type { IHaltStore } from '../contracts/IHaltStore.js';
+import type { IHookInstaller } from '../contracts/IHookInstaller.js';
+import type { IInstanceLock } from '../contracts/IInstanceLock.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { IProcessHost } from '../contracts/IProcessHost.js';
+import type { IStateRecorder } from '../contracts/IStateRecorder.js';
+import type { ISyncScheduler } from '../contracts/ISyncScheduler.js';
+import type { IWatcher } from '../contracts/IWatcher.js';
+/** What the STARTED line reports besides the upstream. */
+export interface DaemonSettings {
+    readonly root: string;
+    readonly quietMs: number;
+    readonly pollMs: number;
+}
+/**
+ * A copy of the first stop signal arriving within this window is the same
+ * stop, not a second one (Decision 91): a forwarding parent's copy arrives
+ * within milliseconds, a person's deliberate second Ctrl-C takes longer.
+ */
+export declare const DUPLICATE_SIGNAL_WINDOW_MS = 500;
+/**
+ * Service: the daemon lifecycle of design 1.16, steps 1 to 10. Steps 2 to 10
+ * run inside a try/finally that releases the lock on every exit path,
+ * including a throw; the final line is logged after the release, so STOPPED
+ * means the lock is gone.
+ */
+export declare class Daemon implements IDaemon {
+    private readonly settings;
+    private readonly lock;
+    private readonly halt;
+    private readonly recovery;
+    private readonly preflight;
+    private readonly hookInstaller;
+    private readonly watcher;
+    private readonly scheduler;
+    private readonly processHost;
+    private readonly logger;
+    /** Lifecycle events for state.json, recorded while the lock is held (design 12.1). */
+    private readonly state;
+    /** Tells a copy of the first stop signal from a second one (Decision 91). */
+    private readonly clock;
+    constructor(settings: DaemonSettings, lock: IInstanceLock, halt: IHaltStore, recovery: IRecovery, preflight: IPreflight, hookInstaller: IHookInstaller, watcher: IWatcher, scheduler: ISyncScheduler, processHost: IProcessHost, logger: ILogger, 
+    /** Lifecycle events for state.json, recorded while the lock is held (design 12.1). */
+    state: IStateRecorder, 
+    /** Tells a copy of the first stop signal from a second one (Decision 91). */
+    clock: IClock);
+    run(): Promise<ExitCode>;
+    /** The holder is this process; its identity is what stateLiveness compares. */
+    private recordStarted;
+    /** Steps 2 to 10, with the lock held. */
+    private runLocked;
+}