@aifight/aifight 0.1.0-alpha.1

package/dist/types/bridge/config.d.ts

@@ -0,0 +1,35 @@
+export type BridgeRuntimeType = "openclaw" | "hermes" | "mock";
+export declare class RuntimeLocalUrlError extends Error {
+    readonly name = "RuntimeLocalUrlError";
+}
+export interface BridgeConfig {
+    readonly version: 1;
+    readonly baseUrl: string;
+    readonly wsUrl: string;
+    readonly agentId: string;
+    readonly agentName: string;
+    readonly suggestedName?: string;
+    readonly apiKey: string;
+    readonly claimUrl?: string;
+    readonly claimToken?: string;
+    readonly runtimeType: BridgeRuntimeType;
+    readonly runtimeLocalUrl: string;
+    readonly runtimeLocalToken?: string;
+    readonly runtimeModel?: string;
+    readonly autoDailyLimit?: number;
+    readonly autoGames?: readonly string[];
+    readonly updatedAt: string;
+}
+export interface RedactedBridgeConfig extends Omit<BridgeConfig, "apiKey" | "runtimeLocalToken" | "claimToken"> {
+    readonly apiKey: string;
+    readonly runtimeLocalToken?: string;
+    readonly claimToken?: string;
+}
+export declare function defaultRuntimeLocalUrl(runtimeType: BridgeRuntimeType): string;
+export declare function normalizeRuntimeLocalUrl(raw: string, runtimeType: BridgeRuntimeType): string;
+export declare function defaultRuntimeModel(runtimeType: BridgeRuntimeType): string;
+export declare function getBridgeConfigPath(): string;
+export declare function removeBridgeConfig(): void;
+export declare function writeBridgeConfig(config: BridgeConfig): void;
+export declare function readBridgeConfig(): BridgeConfig;
+export declare function redactBridgeConfig(config: BridgeConfig): RedactedBridgeConfig;

package/dist/types/bridge/hermes-provider.d.ts

@@ -0,0 +1,9 @@
+import type { BridgeRuntimeProvider } from "./provider";
+export interface HermesRuntimeProviderOptions {
+    readonly agentId: string;
+    readonly baseUrl?: string;
+    readonly token?: string;
+    readonly model?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createHermesRuntimeProvider(opts: HermesRuntimeProviderOptions): BridgeRuntimeProvider;

package/dist/types/bridge/openclaw-provider.d.ts

@@ -0,0 +1,9 @@
+import type { BridgeRuntimeProvider } from "./provider";
+export interface OpenClawRuntimeProviderOptions {
+    readonly agentId: string;
+    readonly baseUrl?: string;
+    readonly token?: string;
+    readonly model?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createOpenClawRuntimeProvider(opts: OpenClawRuntimeProviderOptions): BridgeRuntimeProvider;

package/dist/types/bridge/pairing.d.ts

@@ -0,0 +1,18 @@
+import { type BridgeConfig, type BridgeRuntimeType } from "./config";
+export interface BridgePairExchangeResponse {
+    readonly agent: {
+        readonly id: string;
+        readonly name: string;
+        readonly api_key: string;
+        readonly runtime_type: BridgeRuntimeType;
+    };
+    readonly ws_url: string;
+    readonly message?: string;
+}
+export interface ExchangePairingCodeOptions {
+    readonly pairingCode: string;
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => Date;
+}
+export declare function exchangePairingCode(opts: ExchangePairingCodeOptions): Promise<BridgeConfig>;

package/dist/types/bridge/provider.d.ts

@@ -0,0 +1,18 @@
+import type { AgentDecisionProvider } from "../agents/agent";
+import type { GameType, LegalAction } from "../decision/types";
+export interface BridgeRuntimeDecisionRequest {
+    readonly game: GameType;
+    readonly matchId: string;
+    readonly playerId?: string;
+    readonly legalActions: readonly LegalAction[];
+    readonly publicState: unknown;
+    readonly timeoutMs: number;
+}
+export interface BridgeRuntimeProvider {
+    readonly name: string;
+    decide(req: BridgeRuntimeDecisionRequest): Promise<string | LegalAction>;
+    healthCheck?(): Promise<boolean>;
+}
+export declare function buildBridgeDecisionProvider(runtimeProvider: BridgeRuntimeProvider): AgentDecisionProvider;
+export declare function createMockRuntimeProvider(): BridgeRuntimeProvider;
+export declare function createUnavailableRuntimeProvider(name: string): BridgeRuntimeProvider;

package/dist/types/bridge/runner.d.ts

@@ -0,0 +1,30 @@
+import { AgentInstance, type AgentInstanceSnapshot } from "../agents/agent";
+import type { BridgeConfig } from "./config";
+import { type BridgeRuntimeProvider } from "./provider";
+export interface BridgeRunnerOptions {
+    readonly config: BridgeConfig;
+    readonly runtimeProvider?: BridgeRuntimeProvider;
+    readonly autoJoinGame?: "texas_holdem" | "liars_dice" | "coup";
+    readonly autoJoinMode?: string;
+    readonly autoJoinOneShot?: boolean;
+    readonly connect?: ConstructorParameters<typeof AgentInstance>[0]["connect"];
+    readonly onLog?: (event: BridgeRunnerLogEvent) => void;
+}
+export interface BridgeRunnerLogEvent {
+    readonly level: "info" | "warning" | "error";
+    readonly code: string;
+    readonly message: string;
+}
+export declare class BridgeRunner {
+    #private;
+    constructor(opts: BridgeRunnerOptions);
+    start(): Promise<AgentInstanceSnapshot>;
+    stop(): Promise<void>;
+    snapshot(): AgentInstanceSnapshot | null;
+    joinQueue(game: "texas_holdem" | "liars_dice" | "coup", mode?: string, opts?: {
+        readonly oneShot?: boolean;
+        readonly count?: number;
+    }): void;
+    leaveQueue(): void;
+    requestManualMatches(game: "texas_holdem" | "liars_dice" | "coup", mode?: string, count?: number): void;
+}

package/dist/types/bridge/service.d.ts

@@ -0,0 +1,55 @@
+export declare const AIFIGHT_SERVICE_NAME = "aifight.service";
+export type BridgeServicePlatform = "linux-systemd-system" | "linux-systemd-user" | "darwin-launchd-user";
+export interface ServiceExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ServiceExecError extends Error {
+    readonly code?: string;
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export type ServiceExecFile = (file: string, args: readonly string[]) => Promise<ServiceExecResult>;
+export interface BridgeServiceDeps {
+    readonly execFile?: ServiceExecFile;
+    readonly platform?: NodeJS.Platform;
+    readonly uid?: number;
+    readonly username?: string;
+    readonly homeDir?: string;
+    readonly aifightExec?: string;
+    readonly nodeExec?: string;
+    readonly runtimeHome?: string;
+    readonly systemdSystemUnitPath?: string;
+    readonly systemdUserUnitPath?: string;
+    readonly launchdPlistPath?: string;
+    readonly launchdLogDir?: string;
+}
+export interface BridgeServiceTarget {
+    readonly platform: BridgeServicePlatform;
+    readonly unitPath: string;
+    readonly nodeExec: string;
+    readonly aifightExec: string;
+    readonly runtimeHome: string;
+}
+export interface BridgeServiceInstallResult extends BridgeServiceTarget {
+    readonly linger: "not_needed" | "enabled" | "failed" | "skipped";
+    readonly warning?: string;
+}
+export interface BridgeServiceStatus extends BridgeServiceTarget {
+    readonly installed: boolean;
+    readonly running: boolean | null;
+    readonly detail: string;
+}
+export declare class BridgeServiceError extends Error {
+    readonly code: string;
+    readonly hint?: string;
+    constructor(code: string, message: string, hint?: string);
+}
+export declare const defaultServiceExecFile: ServiceExecFile;
+export declare function installBridgeService(deps?: BridgeServiceDeps): Promise<BridgeServiceInstallResult>;
+export declare function uninstallBridgeService(deps?: BridgeServiceDeps): Promise<BridgeServiceTarget>;
+export declare function startBridgeService(deps?: BridgeServiceDeps): Promise<BridgeServiceTarget>;
+export declare function stopBridgeService(deps?: BridgeServiceDeps): Promise<BridgeServiceTarget>;
+export declare function restartBridgeService(deps?: BridgeServiceDeps): Promise<BridgeServiceTarget>;
+export declare function statusBridgeService(deps?: BridgeServiceDeps): Promise<BridgeServiceStatus>;
+export declare function resolveBridgeServiceTarget(deps?: BridgeServiceDeps): Promise<BridgeServiceTarget>;

package/dist/types/bridge/update-check.d.ts

@@ -0,0 +1,23 @@
+export type BridgeUpdateStatus = "current" | "update_recommended" | "unsupported" | "unknown";
+export interface BridgeVersionPolicy {
+    readonly minimumSupportedVersion: string;
+    readonly recommendedVersion: string;
+    readonly latestVersion: string;
+    readonly updateCommand: string;
+    readonly releaseNotesUrl?: string;
+    readonly policy?: string;
+}
+export interface BridgeUpdateCheck {
+    readonly status: BridgeUpdateStatus;
+    readonly currentVersion: string;
+    readonly policy?: BridgeVersionPolicy;
+    readonly message: string;
+}
+export interface CheckBridgeUpdateOptions {
+    readonly baseUrl: string;
+    readonly currentVersion: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export declare function checkBridgeUpdate(opts: CheckBridgeUpdateOptions): Promise<BridgeUpdateCheck>;
+export declare function evaluatePolicy(currentVersion: string, policy: BridgeVersionPolicy): BridgeUpdateCheck;

package/dist/types/cli/agent-resolver.d.ts

@@ -0,0 +1,25 @@
+import type { ControlClient } from "./control-client";
+export type AgentResolverErrorKind = "no_agents" | "ambiguous";
+export declare class AgentResolverError extends Error {
+    readonly name = "AgentResolverError";
+    readonly kind: AgentResolverErrorKind;
+    readonly availableNames?: readonly string[];
+    constructor(kind: AgentResolverErrorKind, message: string, availableNames?: readonly string[]);
+}
+export interface AgentResolverOptions {
+    /** Only the .get(...) method is used — typed via Pick so tests can
+     *  inject minimal mocks without implementing post/delete. */
+    readonly client: Pick<ControlClient, "get">;
+    /** When non-empty, used as-is without contacting the daemon. */
+    readonly explicitAgent?: string;
+    /** Default true. --json mode passes false so the implicit-choice log
+     *  doesn't pollute machine-readable output. */
+    readonly logImplicitChoice?: boolean;
+    /** stderr sink for the implicit-choice log line. Default
+     *  process.stderr.write. */
+    readonly onLog?: (message: string) => void;
+}
+export interface AgentResolver {
+    resolve(): Promise<string>;
+}
+export declare function createAgentResolver(opts: AgentResolverOptions): AgentResolver;

package/dist/types/cli/argv.d.ts

@@ -0,0 +1,13 @@
+export type FlagValue = string | number | boolean;
+export interface FlagSpec {
+    readonly name: string;
+    readonly type: "string" | "number" | "boolean";
+    readonly required?: boolean;
+    readonly default?: FlagValue;
+}
+export interface ParsedArgv {
+    readonly positional: readonly string[];
+    readonly flags: Readonly<Record<string, FlagValue>>;
+    readonly errors: readonly string[];
+}
+export declare function parseArgs(argv: readonly string[], spec: readonly FlagSpec[]): ParsedArgv;

package/dist/types/cli/commands/agent-list.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runAgentList(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/agent-status.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runAgentStatus(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-accept.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeAccept(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-challenge.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeChallenge(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-connect.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeConnect(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-register.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeRegister(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-run.d.ts

@@ -0,0 +1,7 @@
+import { type BridgeConfig } from "../../bridge/config";
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeRun(args: HandlerArgs, env: HandlerEnv): Promise<number>;
+export declare function runBridgeWithConfig(opts: {
+    readonly config: BridgeConfig;
+    readonly env: HandlerEnv;
+}): Promise<number>;

package/dist/types/cli/commands/bridge-service.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeService(args: HandlerArgs, env: HandlerEnv): Promise<number>;
+export declare function offerBridgeServiceInstall(env: HandlerEnv): Promise<"installed" | "declined" | "unavailable">;

package/dist/types/cli/commands/bridge-set.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeSet(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-start.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeStart(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-status.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runBridgeStatus(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/bridge-uninstall.d.ts

@@ -0,0 +1,4 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+import { type EnvKeyPrevious } from "./runtime-setup-state";
+export declare function runBridgeUninstall(args: HandlerArgs, env: HandlerEnv): Promise<number>;
+export declare function restoreEnvText(existing: string, previous: Record<string, EnvKeyPrevious>): string;

package/dist/types/cli/commands/config-init.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared.js";
+export declare function runConfigInit(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/config-probe.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared.js";
+export declare function runConfigProbe(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/config-validate.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared.js";
+export declare function runConfigValidate(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/daily-off.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runDailyOff(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/daily-on.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runDailyOn(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/daily-set.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runDailySet(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/daily-show.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runDailyShow(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runDoctor(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/init.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runInit(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/join.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runJoin(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/leave.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runLeave(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runMcp(args: HandlerArgs, _env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/runtime-management.d.ts

@@ -0,0 +1,16 @@
+import type { HandlerEnv } from "../shared";
+export interface ExecResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+type RuntimeName = "openclaw" | "hermes";
+export declare function findExecutable(name: string): string | undefined;
+export declare function execCommand(command: string, args: readonly string[]): Promise<ExecResult>;
+export declare function writeExecResult(env: HandlerEnv, label: string, result: ExecResult): void;
+export declare function promptYesNo(env: HandlerEnv, question: string): Promise<boolean>;
+export declare function promptYesNoDefaultNo(env: HandlerEnv, question: string): Promise<boolean>;
+export declare function offerGatewayRestart(env: HandlerEnv, runtime: RuntimeName, reason: string): Promise<boolean>;
+export declare function systemdUnitIsActive(result: ExecResult): boolean;
+export declare function hermesRestartUnavailable(result: ExecResult): boolean;
+export {};

package/dist/types/cli/commands/runtime-setup-state.d.ts

@@ -0,0 +1,21 @@
+export interface EnvKeyPrevious {
+    readonly wasActive: boolean;
+    readonly value?: string;
+}
+export interface RuntimeSetupState {
+    readonly version: 1;
+    readonly updatedAt: string;
+    readonly openclaw?: {
+        readonly responsesEnabledByAIFight: boolean;
+        readonly updatedAt: string;
+    };
+    readonly hermes?: {
+        readonly envPath: string;
+        readonly previous: Record<string, EnvKeyPrevious>;
+        readonly updatedAt: string;
+    };
+}
+export declare function getRuntimeSetupStatePath(): string;
+export declare function readRuntimeSetupState(): RuntimeSetupState | undefined;
+export declare function mergeRuntimeSetupState(patch: Omit<Partial<RuntimeSetupState>, "version" | "updatedAt">): void;
+export declare function removeRuntimeSetupState(): void;

package/dist/types/cli/commands/runtime-setup.d.ts

@@ -0,0 +1,23 @@
+import type { BridgeRuntimeType } from "../../bridge/config";
+import type { HandlerEnv } from "../shared";
+export interface RuntimeSetupResult {
+    readonly runtimeLocalToken?: string;
+}
+interface RuntimeSetupOptions {
+    readonly env: HandlerEnv;
+    readonly runtimeType: BridgeRuntimeType;
+    readonly runtimeLocalUrl: string;
+    readonly runtimeLocalToken?: string;
+    readonly runtimeModel?: string;
+    readonly jsonMode: boolean;
+}
+type ProbeStatus = "ready" | "endpoint_reachable" | "disabled" | "auth_failed" | "unreachable";
+interface ProbeResult {
+    readonly status: ProbeStatus;
+    readonly detail: string;
+}
+export declare function offerRuntimeSetup(opts: RuntimeSetupOptions): Promise<RuntimeSetupResult>;
+export declare function probeOpenClaw(env: HandlerEnv, baseUrl: string, token?: string, model?: string): Promise<ProbeResult>;
+export declare function probeHermes(env: HandlerEnv, baseUrl: string, token?: string, model?: string): Promise<ProbeResult>;
+export declare function upsertEnvText(existing: string, values: Record<string, string>): string;
+export {};

package/dist/types/cli/commands/serve.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runServe(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/service/launchd.d.ts

@@ -0,0 +1,71 @@
+import type { ServiceTarget } from "./types";
+import { type ServiceExecFile } from "./platform";
+export declare class LaunchdAlreadyInstalledDiffError extends Error {
+    readonly code: "client_already_installed_diff";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class LaunchdNotInstalledError extends Error {
+    readonly code: "client_not_installed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class LaunchdInstallFailedError extends Error {
+    readonly code: "client_install_failed";
+    readonly hint?: string;
+    /** Stage taxonomy distinct from systemd's (which is daemon-reload /
+     *  enable / start). Launchd combines register+start into bootstrap, so
+     *  the natural stages are the prerequisites (log dir + plist write),
+     *  the bootstrap call itself, and the post-bootstrap verify. */
+    readonly stage: "log-dir" | "write-plist" | "bootstrap" | "verify";
+    constructor(stage: LaunchdInstallFailedError["stage"], message: string, hint?: string);
+}
+export declare class LaunchdUninstallFailedError extends Error {
+    readonly code: "client_uninstall_failed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class LaunchdStartFailedError extends Error {
+    readonly code: "client_start_failed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class LaunchdStopFailedError extends Error {
+    readonly code: "client_stop_failed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare function escapeXmlText(s: string): string;
+export declare const LAUNCHD_LABEL = "ai.aifight.runtime";
+export interface LaunchdTargetOptions {
+    /** Absolute path of the resolved `aifight` binary. Step 4
+     *  `resolveAifightExec()` produces this; tests inject any string. */
+    readonly aifightExec: string;
+    /** Absolute path of the plist — typically
+     *  `~/Library/LaunchAgents/ai.aifight.runtime.plist`. Tests inject a
+     *  tmp dir. */
+    readonly plistPath: string;
+    /** Absolute log directory — typically `~/Library/Logs/aifight`.
+     *  Install creates this if missing; uninstall preserves it unless
+     *  `--purge`. */
+    readonly logDir: string;
+    /** AIFIGHT_RUNTIME_HOME baked into the plist EnvironmentVariables. */
+    readonly runtimeHome: string;
+    /** Effective user id for `gui/$UID` selector. Production uses
+     *  `process.getuid?.() ?? 0`; tests inject any integer. */
+    readonly uid: number;
+    /** Factory-time `RunAtLoad` setting (rev3 B4 — see module header for
+     *  the systemd vs launchd asymmetry rationale).
+     *    - true:  plist writes `RunAtLoad=true`; install bootstraps and
+     *      then verifies via `launchctl print` (daemon should be running).
+     *    - false: plist writes `RunAtLoad=false`; install still bootstraps
+     *      (registers LaunchAgent) but does NOT verify (the daemon is
+     *      intentionally idle until `aifight service start` kickstarts
+     *      it). */
+    readonly autoStart: boolean;
+    /** Defaults to `defaultExecFile` (production). Tests pass a mock that
+     *  records calls + returns canned stdout/stderr without spawning a
+     *  real subprocess. */
+    readonly execFile?: ServiceExecFile;
+}
+export declare function createLaunchdTarget(opts: LaunchdTargetOptions): ServiceTarget;

package/dist/types/cli/commands/service/platform.d.ts

@@ -0,0 +1,69 @@
+import type { ServicePlatform } from "./types";
+/** OS-level platform — intermediate value before service-manager probe.
+ *  - "linux" / "darwin": candidate for service install; needs probe.
+ *  - "unsupported": Windows / FreeBSD / other; short-circuits without probe. */
+export type OsPlatform = "linux" | "darwin" | "unsupported";
+/** Sync, pure, `process.platform`-only OS detection (rev4 B2 + F4 fold).
+ *  No I/O, no subprocess. Tests stub `process.platform` via Object.defineProperty. */
+export declare function detectOsPlatform(): OsPlatform;
+/** Result of an injected execFile call. Promise resolves on exit 0;
+ *  rejects with `ServiceExecFileError` on ENOENT, non-zero exit, or
+ *  any other subprocess error. Mirrors `util.promisify(child_process.execFile)`
+ *  semantics so the production default below is a thin adapter. */
+export interface ServiceExecFileResult {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ServiceExecFileError extends Error {
+    /** Node ErrnoException code, e.g. "ENOENT" when the binary is not in PATH. */
+    readonly code?: string;
+    /** Captured before failure (when the subprocess emitted output then exited
+     *  non-zero). Empty string when no output was captured. */
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export type ServiceExecFile = (file: string, args: readonly string[]) => Promise<ServiceExecFileResult>;
+/** Production default — wraps Node `child_process.execFile` with a 2 s
+ *  timeout suitable for cheap version probes. Tests pass an explicit mock
+ *  so this is never invoked in CI. Exposed so callers (service-install.ts
+ *  in Step 4) can reuse it instead of recreating the adapter. */
+export declare const defaultExecFile: ServiceExecFile;
+export interface ProbeServicePlatformOptions {
+    readonly execFile: ServiceExecFile;
+    /** Defaults to `detectOsPlatform()`; tests pass explicit value to avoid
+     *  Object.defineProperty(process, "platform") gymnastics. */
+    readonly osPlatform?: OsPlatform;
+}
+/** Async, injectable, only-read probe.
+ *  - osPlatform == "unsupported" → short-circuit `unsupported` (NEVER
+ *    invokes execFile). Tests assert this with a spy that throws if called.
+ *  - osPlatform == "linux" → `execFile("systemctl", ["--user", "--version"])`.
+ *  - osPlatform == "darwin" → `execFile("launchctl", ["version"])`.
+ *  - any rejection (ENOENT / non-zero exit / timeout / unexpected throw),
+ *    or stdout/stderr containing a known failure marker (e.g.
+ *    "Failed to connect to bus" — systemd `--user` not running) → `unsupported`.
+ *  - resolution + clean stdout/stderr → corresponding `linux-systemd-user`
+ *    or `darwin-launchd-user`. */
+export declare function probeServicePlatform(opts: ProbeServicePlatformOptions): Promise<ServicePlatform>;
+/** rev4 contract — service-specific error class. NOT a `UsageError`,
+ *  because plain `UsageError` funnels through `main.ts emitUsageError` and
+ *  produces only `client_usage_error`. Service handlers catch
+ *  `ServicePlatformError` and call `emitServiceError(env, jsonMode, 2,
+ *  e.code, e.message, e.hint)`. */
+export declare class ServicePlatformError extends Error {
+    readonly code: "client_platform_unsupported" | "client_service_manager_missing";
+    readonly hint?: string;
+    constructor(code: ServicePlatformError["code"], message: string, hint?: string);
+}
+export interface EnsureSupportedPlatformOptions extends Partial<ProbeServicePlatformOptions> {
+}
+/** Composes `detectOsPlatform()` + `probeServicePlatform()`.
+ *  - Returns the resolved supported platform on success.
+ *  - Throws `ServicePlatformError` on unsupported with:
+ *      Windows / non-linux + non-darwin → `client_platform_unsupported`
+ *        + hint mentioning Windows or "platform <p>".
+ *      linux / darwin but service manager unreachable →
+ *        `client_service_manager_missing` + hint mentioning systemd `--user`
+ *        or launchctl.
+ *  Caller handler maps the error via `emitServiceError(... e.code, e.message, e.hint)`. */
+export declare function ensureSupportedPlatform(opts?: EnsureSupportedPlatformOptions): Promise<"linux-systemd-user" | "darwin-launchd-user">;

package/dist/types/cli/commands/service/systemd.d.ts

@@ -0,0 +1,55 @@
+import type { ServiceTarget } from "./types";
+import { type ServiceExecFile } from "./platform";
+export declare class AlreadyInstalledDiffError extends Error {
+    readonly code: "client_already_installed_diff";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class NotInstalledError extends Error {
+    readonly code: "client_not_installed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class InstallFailedError extends Error {
+    readonly code: "client_install_failed";
+    readonly hint?: string;
+    /** Stage the failure happened at — useful for human-mode messages. */
+    readonly stage: "daemon-reload" | "enable" | "start";
+    constructor(stage: InstallFailedError["stage"], message: string, hint?: string);
+}
+export declare class UninstallFailedError extends Error {
+    readonly code: "client_uninstall_failed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class StartFailedError extends Error {
+    readonly code: "client_start_failed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare class StopFailedError extends Error {
+    readonly code: "client_stop_failed";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export declare function quoteSystemdExecPath(p: string): string;
+export declare const SYSTEMD_UNIT_NAME = "aifight.service";
+export interface SystemdTargetOptions {
+    /** Absolute path of the resolved `aifight` binary. Step 4
+     *  `resolveAifightExec()` produces this; tests inject any string. */
+    readonly aifightExec: string;
+    /** Absolute path of the unit file — typically
+     *  `~/.config/systemd/user/aifight.service`. Tests inject a tmp dir. */
+    readonly unitPath: string;
+    /** AIFIGHT_RUNTIME_HOME baked into the unit. Tests inject any string. */
+    readonly runtimeHome: string;
+    /** Optional `--env-file` absolute path (rev3 B3 — systemd-only).
+     *  Handler validates existence + chmod before passing here; target
+     *  trusts the value. */
+    readonly envFile?: string;
+    /** Defaults to `defaultExecFile` (production). Tests pass a mock that
+     *  records calls + returns canned stdout/stderr without spawning a
+     *  real subprocess. */
+    readonly execFile?: ServiceExecFile;
+}
+export declare function createSystemdTarget(opts: SystemdTargetOptions): ServiceTarget;