@indigoai-us/hq-cli 5.125.0 → 5.126.0

package/dist/lib/lanes/types.js

@@ -0,0 +1,217 @@
+/**
+ * Lane record, question routing record, envelope, and config types (spec §3,
+ * §4, §5.5, §6.2). Finite sets are string-literal unions plus `const` arrays
+ * so the command layer can validate flags explicitly.
+ */
+import { LanesError, LaneSchemaError } from "./errors.js";
+export const LANE_SCHEMA_VERSION = "hq-lane.v1";
+export const QUESTION_SCHEMA_VERSION = "hq-lane-question.v1";
+export const ENVELOPE_SCHEMA_VERSION = "hq-lane-envelope.v1";
+export const CONFIG_SCHEMA_VERSION = "hq-lanes-config.v1";
+export const LANE_STATES = [
+    "queued",
+    "running",
+    "awaiting_input",
+    "blocked",
+    "done",
+    "failed",
+    "interrupted",
+    "cancelled",
+    "killed",
+];
+/** Exact terminal set from spec §6.7. `awaiting_input` and `blocked` are not terminal. */
+export const TERMINAL_LANE_STATES = [
+    "done",
+    "failed",
+    "interrupted",
+    "cancelled",
+    "killed",
+];
+export const LANE_PROVIDERS = ["claude", "codex", "grok"];
+export const QUEUED_REASONS = ["cap", "queue_position", "throttle"];
+export const HOST_KINDS = ["local", "outpost"];
+export const SENIOR_KINDS = ["session", "lane", "user"];
+export const ENVELOPE_DECISIONS = ["done", "ask", "blocked"];
+export const STORY_STATUSES = [
+    "queued",
+    "in_progress",
+    "review",
+    "done",
+];
+export const QUESTION_STATUSES = [
+    "pending",
+    "answered",
+    "cancelled",
+    "expired",
+];
+export const RAISED_VIA = ["cli", "envelope"];
+export const ROUTING_REASONS = [
+    "asked",
+    "escalated",
+    "audience_ended",
+    "reparented",
+    "unanswered_timeout",
+    "cancelled",
+];
+export const QUESTION_BODY_STORES = ["company", "personal"];
+export const LIVENESS_STATES = ["live", "idle", "ended", "lost"];
+export const HISTORY_CAP = 50;
+const TERMINAL_SET = new Set(TERMINAL_LANE_STATES);
+export function isLaneState(value) {
+    return typeof value === "string" && LANE_STATES.includes(value);
+}
+export function isTerminalLaneState(value) {
+    return typeof value === "string" && TERMINAL_SET.has(value);
+}
+export function isLaneProvider(value) {
+    return (typeof value === "string" &&
+        LANE_PROVIDERS.includes(value));
+}
+export function isSeniorKind(value) {
+    return (typeof value === "string" &&
+        SENIOR_KINDS.includes(value));
+}
+export function isHostKind(value) {
+    return (typeof value === "string" &&
+        HOST_KINDS.includes(value));
+}
+export function isEnvelopeDecision(value) {
+    return (typeof value === "string" &&
+        ENVELOPE_DECISIONS.includes(value));
+}
+export function isQuestionStatus(value) {
+    return (typeof value === "string" &&
+        QUESTION_STATUSES.includes(value));
+}
+export function isLivenessState(value) {
+    return (typeof value === "string" &&
+        LIVENESS_STATES.includes(value));
+}
+export function parseLaneProvider(value) {
+    if (isLaneProvider(value))
+        return value;
+    throw new LanesError("unknown_provider", `Unknown provider ${JSON.stringify(value)}. Accepted: ${LANE_PROVIDERS.join(", ")}`, { accepted: [...LANE_PROVIDERS], value });
+}
+export function parseLaneState(value) {
+    if (isLaneState(value))
+        return value;
+    throw new LanesError("unknown_state", `Unknown lane state ${JSON.stringify(value)}. Accepted: ${LANE_STATES.join(", ")}`, { accepted: [...LANE_STATES], value });
+}
+export function parseQuestionStatus(value) {
+    if (isQuestionStatus(value))
+        return value;
+    throw new LanesError("unknown_status", `Unknown question status ${JSON.stringify(value)}. Accepted: ${QUESTION_STATUSES.join(", ")}`, { accepted: [...QUESTION_STATUSES], value });
+}
+export function parseLivenessState(value) {
+    if (isLivenessState(value))
+        return value;
+    throw new LanesError("unknown_state", `Unknown session liveness state ${JSON.stringify(value)}. Accepted: ${LIVENESS_STATES.join(", ")}`, { accepted: [...LIVENESS_STATES], value });
+}
+export function parseSeniorKind(value) {
+    if (isSeniorKind(value))
+        return value;
+    throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new LaneSchemaError(`Expected non-empty string for ${field}`, {
+            field,
+        });
+    }
+    return value;
+}
+export function parseMajorSchema(schemaVersion, expectedPrefix, expectedMajor) {
+    const match = new RegExp(`^${expectedPrefix}\\.v(\\d+)$`).exec(schemaVersion);
+    if (!match) {
+        throw new LaneSchemaError(`Unknown schema_version ${JSON.stringify(schemaVersion)} (expected ${expectedPrefix}.v${expectedMajor})`, { schema_version: schemaVersion, expected: `${expectedPrefix}.v${expectedMajor}` });
+    }
+    const major = Number(match[1]);
+    if (major !== expectedMajor) {
+        throw new LaneSchemaError(`Unsupported ${expectedPrefix} major version ${major} (found ${schemaVersion})`, { schema_version: schemaVersion, major });
+    }
+}
+export function parseLaneEnvelope(raw) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Lane envelope must be a JSON object");
+    }
+    const extra = Object.keys(raw).filter((key) => ![
+        "schema_version",
+        "decision",
+        "summary",
+        "questions",
+        "story_status",
+        "artifacts",
+        "blocked_reason",
+    ].includes(key));
+    if (extra.length > 0) {
+        throw new LaneSchemaError(`Lane envelope rejects unknown properties: ${extra.join(", ")}`, { extra });
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane-envelope", 1);
+    if (!isEnvelopeDecision(raw.decision)) {
+        throw new LaneSchemaError(`Unknown envelope decision ${JSON.stringify(raw.decision)}. Accepted: ${ENVELOPE_DECISIONS.join(", ")}`, { accepted: [...ENVELOPE_DECISIONS], value: raw.decision });
+    }
+    const summary = requireString(raw.summary, "summary");
+    if (typeof raw.story_status !== "string" ||
+        !STORY_STATUSES.includes(raw.story_status)) {
+        throw new LaneSchemaError(`Unknown story_status ${JSON.stringify(raw.story_status)}. Accepted: ${STORY_STATUSES.join(", ")}`, { accepted: [...STORY_STATUSES], value: raw.story_status });
+    }
+    if (!Array.isArray(raw.artifacts)) {
+        throw new LaneSchemaError("Envelope artifacts must be an array");
+    }
+    const questions = raw.questions;
+    if (raw.decision === "ask") {
+        if (!Array.isArray(questions) || questions.length === 0) {
+            throw new LaneSchemaError('questions must be non-empty when decision is "ask"');
+        }
+    }
+    else if (questions !== undefined) {
+        if (!Array.isArray(questions) || questions.length !== 0) {
+            throw new LaneSchemaError('questions must be omitted or empty unless decision is "ask"');
+        }
+    }
+    if (raw.decision === "blocked") {
+        if (typeof raw.blocked_reason !== "string" || raw.blocked_reason.length === 0) {
+            throw new LaneSchemaError('blocked_reason is required when decision is "blocked"');
+        }
+    }
+    else if (raw.blocked_reason !== undefined) {
+        throw new LaneSchemaError('blocked_reason is present exactly when decision is "blocked"');
+    }
+    const envelope = {
+        schema_version: ENVELOPE_SCHEMA_VERSION,
+        decision: raw.decision,
+        summary,
+        story_status: raw.story_status,
+        artifacts: raw.artifacts,
+    };
+    if (Array.isArray(questions) && questions.length > 0) {
+        envelope.questions = questions.map((item, index) => {
+            if (!isPlainObject(item)) {
+                throw new LaneSchemaError(`questions[${index}] must be an object`);
+            }
+            const options = item.options;
+            if (!Array.isArray(options) ||
+                options.some((opt) => typeof opt !== "string")) {
+                throw new LaneSchemaError(`questions[${index}].options must be string[]`);
+            }
+            const parsed = {
+                question: requireString(item.question, `questions[${index}].question`),
+                context: requireString(item.context, `questions[${index}].context`),
+                options,
+            };
+            if (item.recommended !== undefined) {
+                parsed.recommended = requireString(item.recommended, `questions[${index}].recommended`);
+            }
+            return parsed;
+        });
+    }
+    if (typeof raw.blocked_reason === "string") {
+        envelope.blocked_reason = raw.blocked_reason;
+    }
+    return envelope;
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/mesh/live/daemon/config.d.ts

@@ -3,6 +3,33 @@ export interface DaemonConfig {
 }
 export declare function daemonConfigPath(daemonDirectory: string): string;
 export declare function verifyHqRoot(candidate: string | undefined): string | null;
+/**
+ * A directory the daemon may be installed for: it must carry
+ * companies/manifest.yaml (what verifyHqRoot demands at runtime) and one of
+ * the tree markers utils/hq-roots.ts accepts (core/, .claude/, personal/).
+ * A bare .claude/ directory — every repo with Claude settings has one — is
+ * not an HQ root and must never be persisted or passed as --hq-root.
+ */
+export declare function isInstallableHqRoot(dir: string): boolean;
+/** Nearest ancestor of startDir (inclusive) that is an installable HQ root, realpath'd; null if none. */
+export declare function findAncestorHqRoot(startDir: string): string | null;
+export interface InstallHqRootResolution {
+    root: string;
+    source: "flag" | "env" | "ancestor";
+}
+/**
+ * Resolve the HQ root `hq mesh daemon install` records and passes to the
+ * service. Precedence: --hq-root, then HQ_ROOT, then the nearest ancestor of
+ * cwd that is an installable HQ root. An explicit value that is not an HQ
+ * root is an error rather than a silent fallback, and with nothing
+ * qualifying the install is refused: an unverified root would be persisted
+ * and trusted by the daemon for company attribution.
+ */
+export declare function resolveInstallHqRoot(opts?: {
+    explicit?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}): InstallHqRootResolution;
 export declare function readDaemonConfig(daemonDirectory: string): DaemonConfig;
 /** Record a verified local HQ checkout without trusting a caller-supplied path at runtime. */
 export declare function registerTrustedHqRoot(daemonDirectory: string, candidate: string | undefined): DaemonConfig;

package/dist/lib/mesh/live/daemon/config.js

@@ -16,6 +16,81 @@ export function verifyHqRoot(candidate) {
         return null;
     }
 }
+/**
+ * A directory the daemon may be installed for: it must carry
+ * companies/manifest.yaml (what verifyHqRoot demands at runtime) and one of
+ * the tree markers utils/hq-roots.ts accepts (core/, .claude/, personal/).
+ * A bare .claude/ directory — every repo with Claude settings has one — is
+ * not an HQ root and must never be persisted or passed as --hq-root.
+ */
+export function isInstallableHqRoot(dir) {
+    if (verifyHqRoot(dir) === null)
+        return false;
+    return ["core", ".claude", "personal"].some((marker) => {
+        try {
+            return fs.statSync(path.join(dir, marker)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Nearest ancestor of startDir (inclusive) that is an installable HQ root, realpath'd; null if none. */
+export function findAncestorHqRoot(startDir) {
+    let dir;
+    try {
+        dir = fs.realpathSync(startDir);
+    }
+    catch {
+        dir = path.resolve(startDir);
+    }
+    for (;;) {
+        if (isInstallableHqRoot(dir))
+            return fs.realpathSync(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve the HQ root `hq mesh daemon install` records and passes to the
+ * service. Precedence: --hq-root, then HQ_ROOT, then the nearest ancestor of
+ * cwd that is an installable HQ root. An explicit value that is not an HQ
+ * root is an error rather than a silent fallback, and with nothing
+ * qualifying the install is refused: an unverified root would be persisted
+ * and trusted by the daemon for company attribution.
+ */
+export function resolveInstallHqRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const cwd = opts.cwd ?? process.cwd();
+    const explicit = opts.explicit?.trim();
+    if (explicit) {
+        if (!isInstallableHqRoot(explicit)) {
+            throw expectedError(`--hq-root ${explicit} is not an HQ root (needs companies/manifest.yaml plus core/, .claude/, or personal/).`);
+        }
+        return { root: fs.realpathSync(explicit), source: "flag" };
+    }
+    const fromEnv = env.HQ_ROOT?.trim();
+    if (fromEnv) {
+        if (!isInstallableHqRoot(fromEnv)) {
+            throw expectedError(`HQ_ROOT=${fromEnv} is not an HQ root (needs companies/manifest.yaml plus core/, .claude/, or personal/). ` +
+                `Fix HQ_ROOT or pass --hq-root <path>.`);
+        }
+        return { root: fs.realpathSync(fromEnv), source: "env" };
+    }
+    const ancestor = findAncestorHqRoot(cwd);
+    if (!ancestor) {
+        throw expectedError(`No HQ root found above ${cwd} (a directory with companies/manifest.yaml plus core/, .claude/, or personal/). ` +
+            `Run from inside your HQ tree or pass --hq-root <path>.`);
+    }
+    return { root: ancestor, source: "ancestor" };
+}
+function expectedError(message) {
+    const err = new Error(message);
+    err.expected = true;
+    return err;
+}
 export function readDaemonConfig(daemonDirectory) {
     try {
         const raw = JSON.parse(fs.readFileSync(daemonConfigPath(daemonDirectory), "utf8"));

package/dist/lib/mesh/live/daemon/index.d.ts

@@ -1,4 +1,4 @@
-export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
+export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, WINDOWS_TASK_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
 export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
 export type { PidLockDeps, PidLockRecord, PidLockResult } from "./pid-lock.js";
 export { CREDENTIAL_RENEWAL_FRACTION, DEFAULT_REFUSED_RETRY_MS, MAX_RETRY_DELAY_MS, MAX_TIMER_DELAY_MS, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, REFUSED_RETRY_ENV, CredentialRenewalManager, CredentialVendError, classifyCredentialVendFailure, clampRetryDelayMs, createContract3Fetcher, defaultRefusedRetryMs, extractVendErrorCode, isCredentialVendRefused, normalizeContract3Bundle, parseRetryAfterMs, realTimerHost, refusedRetryDelayMs, renewalDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
@@ -12,9 +12,10 @@ export type { DaemonStateFile, PresenceRefusalState } from "./state.js";
 export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
 export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
 export type { BoardReader, BoardRefreshDeps, BoardStorySnapshot } from "./board-refresh.js";
-export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, restartDaemonServiceIfInstalled, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
+export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, restartDaemonServiceIfInstalled, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, parseSchtasksLastResult, parseWindowsTaskHqRoot, readRecordedWindowsHqRoot, schtasksLastResultFailed, uninstallDaemonService, windowsLaunchMode, windowsLogonNotice, } from "./install.js";
 export type { DaemonInstallPlatform, InstallPaths, InstallResult, } from "./install.js";
-export { daemonConfigPath, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
+export { daemonConfigPath, findAncestorHqRoot, isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, resolveInstallHqRoot, verifyHqRoot, } from "./config.js";
+export type { InstallHqRootResolution } from "./config.js";
 export type { DaemonConfig } from "./config.js";
 export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatDaemonDoctor, } from "./doctor.js";
 export type { DaemonDoctorDeps, DaemonDoctorReport } from "./doctor.js";

package/dist/lib/mesh/live/daemon/index.js

@@ -1,4 +1,4 @@
-export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
+export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, WINDOWS_TASK_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
 export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
 export { CREDENTIAL_RENEWAL_FRACTION, DEFAULT_REFUSED_RETRY_MS, MAX_RETRY_DELAY_MS, MAX_TIMER_DELAY_MS, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, REFUSED_RETRY_ENV, CredentialRenewalManager, CredentialVendError, classifyCredentialVendFailure, clampRetryDelayMs, createContract3Fetcher, defaultRefusedRetryMs, extractVendErrorCode, isCredentialVendRefused, normalizeContract3Bundle, parseRetryAfterMs, realTimerHost, refusedRetryDelayMs, renewalDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
 export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
@@ -6,8 +6,8 @@ export { CLOSE_LOG_ALWAYS_COUNT, CLOSE_LOG_INTERVAL_MS, CONNECT_STABLE_GRACE_MS,
 export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
 export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
 export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
-export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, restartDaemonServiceIfInstalled, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
-export { daemonConfigPath, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
+export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, restartDaemonServiceIfInstalled, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, parseSchtasksLastResult, parseWindowsTaskHqRoot, readRecordedWindowsHqRoot, schtasksLastResultFailed, uninstallDaemonService, windowsLaunchMode, windowsLogonNotice, } from "./install.js";
+export { daemonConfigPath, findAncestorHqRoot, isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, resolveInstallHqRoot, verifyHqRoot, } from "./config.js";
 export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatDaemonDoctor, } from "./doctor.js";
 export { scopeBundleToAgentIdentity, } from "./credentials.js";
 export { FLUSH_INTERVAL_MS, DAEMON_VERSION_DRIFT_EXIT_CODE, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -4,13 +4,36 @@
  * - macOS: LaunchAgent ai.getindigo.hq-mesh-daemon
  * - Linux: systemd user unit hq-mesh-daemon.service
  *   (documented fallback: root-owned unit running as ec2-user)
+ * - Windows: per-user Scheduled Task ai.getindigo.hq-mesh-daemon registered
+ *   from a rendered task XML via schtasks.exe (no native dependencies)
  *
  * The unit embeds the hq binary resolved at install time. Logs go to
  * ~/.hq/work-mesh/daemon/log (rotation at 5MB handled by the daemon).
  * Tests must not actually install services — use a temp HOME/prefix.
  */
 import * as fs from "node:fs";
-export type DaemonInstallPlatform = "darwin" | "linux" | "other";
+export type DaemonInstallPlatform = "darwin" | "linux" | "win32" | "other";
+/** Result of one schtasks.exe invocation (tests inject; never the real binary). */
+export interface SchtasksResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type SchtasksRunner = (args: string[]) => SchtasksResult;
+/**
+ * `schtasks /End` terminates the task's root process only. The daemon is
+ * launched through `conhost.exe --headless`, so ending the task kills conhost
+ * and leaves node running as an orphan that still holds the pid lock. Stop
+ * the recorded daemon pid explicitly. Returns the pid that was signalled, or
+ * null when no live daemon pid was recorded.
+ */
+export declare function stopWindowsDaemonProcess(dir: string, deps?: {
+    readFileSync?: typeof fs.readFileSync;
+    existsSync?: typeof fs.existsSync;
+    kill?: (pid: number) => void;
+    selfPid?: number;
+}): number | null;
+export declare const defaultSchtasks: SchtasksRunner;
 export interface InstallPaths {
     home: string;
     hqBinary: string;
@@ -21,10 +44,22 @@ export interface InstallPaths {
     plistPath: string;
     systemdUserDir: string;
     systemdUnitPath: string;
+    /** Windows: rendered Task Scheduler XML kept under the daemon dir. */
+    windowsTaskXmlPath: string;
+    /** Windows: `DOMAIN\user` the task is registered for (logon trigger + principal). */
+    windowsUser: string;
+    /**
+     * Windows: `conhost.exe` used as `conhost --headless node hq ...` so the
+     * logon-triggered daemon gets no visible console window. Undefined when the
+     * host has no conhost (the task then runs node directly).
+     */
+    windowsHeadlessLauncher?: string;
     /** When true, render the root/ec2-user system unit instead of user unit. */
     systemUser?: string;
     /** Verified HQ root to persist and pass to the installed service. */
     hqRoot?: string;
+    /** How hqRoot was chosen (shown in the Windows install confirmation). */
+    hqRootSource?: "flag" | "env" | "ancestor";
 }
 export interface InstallResult {
     platform: DaemonInstallPlatform;
@@ -34,6 +69,22 @@ export interface InstallResult {
     dest?: string;
     running?: boolean;
     message: string;
+    /**
+     * Windows status: the task's "Last Result" code from `schtasks /Query /V`
+     * (normalized to unsigned 32-bit), or null when unavailable.
+     */
+    lastResult?: number | null;
+    /** Windows status: true when lastResult indicates the last start failed. */
+    lastRunFailed?: boolean;
+    /** One plain line of operator context (Windows: logged-on-only visibility). */
+    notice?: string;
+    /**
+     * Windows status: HQ root read back from the registered task XML (else the
+     * persisted daemon config), never re-resolved from cwd. Null when unknown.
+     */
+    recordedHqRoot?: string | null;
+    /** Windows status: whether recordedHqRoot still passes isInstallableHqRoot. */
+    rootValid?: boolean;
 }
 /** Best-effort restart result used after an in-place CLI upgrade. */
 export interface RestartDaemonResult {
@@ -54,6 +105,8 @@ export declare function restartDaemonServiceIfInstalled(opts?: {
     run?: (command: string, args: string[]) => {
         status: number | null;
     };
+    /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */
+    kill?: (pid: number) => void;
 }): RestartDaemonResult;
 export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstallPlatform;
 /**
@@ -76,7 +129,34 @@ export declare function buildInstallPaths(opts: {
     argv?: string[];
     execPath?: string;
     hqRoot?: string;
+    hqRootSource?: "flag" | "env" | "ancestor";
+    /** Windows account (`DOMAIN\user`) the task runs as; defaults to the current user. */
+    windowsUser?: string;
+    /** Windows headless launcher override (tests); defaults to %SystemRoot%\System32\conhost.exe when present. */
+    windowsHeadlessLauncher?: string | null;
 }): InstallPaths;
+/** `DOMAIN\user` for the current account, as Task Scheduler expects. */
+export declare function resolveWindowsUser(env?: NodeJS.ProcessEnv): string;
+/**
+ * `conhost.exe --headless` is undocumented. It shipped with the ConPTY
+ * conhost in Windows 10 1809 (build 17763); older conhost builds reject the
+ * flag and the task would fail on every logon. Gate on the kernel build
+ * reported by os.release() ("10.0.<build>") plus a presence check.
+ */
+export declare const WINDOWS_CONHOST_HEADLESS_MIN_BUILD = 17763;
+/** Build number from an os.release() string such as "10.0.26200"; null if unparsable. */
+export declare function parseWindowsBuild(release: string): number | null;
+/**
+ * `conhost.exe --headless` (Windows 10 1809+) runs a console app with no
+ * window. Returns the launcher path only when conhost.exe exists under
+ * SystemRoot and the host build is new enough to honour `--headless`.
+ */
+export declare function resolveWindowsHeadlessLauncher(env?: NodeJS.ProcessEnv, existsSync?: typeof fs.existsSync, release?: string): string | undefined;
+export type WindowsLaunchMode = "conhost-headless" | "direct";
+/** Which launch wrapper the rendered task uses (recorded in the install message). */
+export declare function windowsLaunchMode(paths: Pick<InstallPaths, "windowsHeadlessLauncher">): WindowsLaunchMode;
+/** The task uses the interactive token, so it exists only inside the user's logon session. */
+export declare function windowsLogonNotice(paths: Pick<InstallPaths, "windowsUser">): string;
 export declare function renderLaunchdPlist(paths: InstallPaths): string;
 export declare function renderSystemdUserUnit(paths: InstallPaths): string;
 /**
@@ -84,6 +164,55 @@ export declare function renderSystemdUserUnit(paths: InstallPaths): string;
  * Documented fallback — written only when --system-user is passed.
  */
 export declare function renderSystemdSystemUnit(paths: InstallPaths): string;
+/**
+ * Windows Task Scheduler definition (schtasks /Create /XML). Runs at logon of
+ * the registering user, hidden, no execution time limit, one instance, and
+ * restarts every minute on failure. HOME/USERPROFILE come from the user's own
+ * session. Task Scheduler XML has no environment block, so the HQ root the
+ * install was run for is passed explicitly as `mesh daemon run --hq-root
+ * <path>` (the launchd/systemd equivalent of Environment=HQ_ROOT) and is also
+ * persisted in the daemon config as a trusted root.
+ *
+ * LogonType is InteractiveToken: S4U ("run whether user is logged on or not")
+ * needs elevation to register, and the interactive token is what an
+ * unprivileged `hq mesh daemon install` can create. As a consequence the task
+ * runs only while the registering user is logged on. The console window that
+ * an interactive-token task would otherwise open is avoided by launching
+ * through `conhost.exe --headless` when the host supports it (see
+ * resolveWindowsHeadlessLauncher); otherwise node is run directly.
+ */
+export declare function renderWindowsTaskXml(paths: InstallPaths): string;
+/** schtasks stores task XML as UTF-16 LE with BOM; match it so /XML parses. */
+export declare function encodeWindowsTaskXml(rendered: string): Buffer;
+/** Status column of `schtasks /Query /FO CSV /NH`: "TaskName","Next Run Time","Status". */
+export declare function parseSchtasksCsvStatus(stdout: string): string | null;
+/**
+ * "Last Result" of `schtasks /Query /TN <name> /V /FO CSV`, normalized to an
+ * unsigned 32-bit code (schtasks prints HRESULT/NTSTATUS values as signed
+ * decimals, e.g. -2147024894 for 0x80070002). Prefers the English header
+ * when present; otherwise uses the fixed column position. Null when the
+ * output carries no task row or the cell is not numeric.
+ */
+export declare function parseSchtasksLastResult(stdout: string): number | null;
+/**
+ * Task Scheduler informational results mean "no failed start": 0 is success,
+ * and every SCHED_S_* code (ready, running, not yet run, terminated, queued,
+ * ...) is a success-severity HRESULT (bit 31 clear) in FACILITY_ITF (0x4)
+ * with code 0x1300-0x13FF, i.e. 0x00041300-0x000413FF. Everything else
+ * (0x8007xxxx, 0xC000xxxx, process exit codes such as 1) is a failed start.
+ */
+export declare function schtasksLastResultFailed(code: number | null): boolean;
+/** `--hq-root <path>` from a rendered task's <Arguments> (XML-escaped, optionally quoted). */
+export declare function parseWindowsTaskHqRoot(xml: string): string | null;
+/**
+ * The HQ root the installed Windows task actually carries: the task XML on
+ * disk first, else the first persisted trusted root. Reads state only; never
+ * resolves from cwd, so status reports what install recorded.
+ */
+export declare function readRecordedWindowsHqRoot(paths: Pick<InstallPaths, "windowsTaskXmlPath" | "daemonDir">, deps?: {
+    existsSync?: typeof fs.existsSync;
+    readFileSync?: typeof fs.readFileSync;
+}): string | null;
 export declare function installDaemonService(opts: {
     platform?: DaemonInstallPlatform;
     paths?: InstallPaths;
@@ -97,6 +226,10 @@ export declare function installDaemonService(opts: {
     reloadSystemd?: () => {
         status: number | null;
     };
+    /** Windows: schtasks.exe runner (tests inject; never the real binary). */
+    schtasks?: SchtasksRunner;
+    /** Windows: terminate the recorded daemon pid when replacing a task (tests inject). */
+    kill?: (pid: number) => void;
 }): InstallResult;
 export declare function uninstallDaemonService(opts: {
     platform?: DaemonInstallPlatform;
@@ -104,6 +237,10 @@ export declare function uninstallDaemonService(opts: {
     unlinkSync?: typeof fs.unlinkSync;
     existsSync?: typeof fs.existsSync;
     deactivate?: (platform: DaemonInstallPlatform, dest: string) => void;
+    /** Windows: schtasks.exe runner (tests inject; never the real binary). */
+    schtasks?: SchtasksRunner;
+    /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */
+    kill?: (pid: number) => void;
 }): InstallResult;
 export declare function daemonServiceStatus(opts: {
     platform?: DaemonInstallPlatform;
@@ -111,6 +248,11 @@ export declare function daemonServiceStatus(opts: {
     existsSync?: typeof fs.existsSync;
     /** Optional live probe (launchctl/systemctl); tests inject. */
     isLoaded?: (platform: DaemonInstallPlatform, dest: string) => boolean;
+    /** Windows: schtasks.exe runner (tests inject; never the real binary). */
+    schtasks?: SchtasksRunner;
+    /** Windows: liveness probe for the daemon pid lock (tests inject). */
+    isProcessAlive?: (pid: number) => boolean;
+    readFileSync?: typeof fs.readFileSync;
 }): InstallResult;
 /** Read baked template files from assets/ (optional; renderers are primary). */
 export declare function readAssetTemplate(name: "launchd.plist.template" | "systemd.user.service.template" | "systemd.system.service.template"): string | null;