cyberlegion 0.3.1 → 0.4.0

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import { Exec, Exec as Exec$1, MuxAdapter, MuxPlacement, MuxProbe, NudgeOptions, probeMultiplexer } from "cyber-mux";
 import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
-
 //#region src/store/store.d.ts
 interface Message {
   id: string;
@@ -56,8 +55,15 @@ interface AgentRecord {
   brief?: string;
   spawnedBy?: string;
   /** Absent ⇒ session (backward compat, no migration). 'standing' = a session-independent,
-   * prune-exempt owner inbox minted by `unit register --standing`. */
-  kind?: 'session' | 'standing';
+   * prune-exempt owner inbox minted by `unit register --standing`. 'service' = a project service's
+   * endpoint (`service.ts`): session-independent and prune-exempt like a standing record, but never
+   * surfaced as owner mail — its mailbox belongs to whichever unit currently owns the service. */
+  kind?: 'session' | 'standing' | 'service';
+  /** Only meaningful on a `kind: 'service'` record — which project service this endpoint is. */
+  service?: {
+    project: string;
+    name: string;
+  };
   /** Only meaningful on a `kind: 'standing'` record — the id of the unit currently standing in for
    * it (`unit claim`), a per-record singleton pointer that moves as the principal moves between
    * units (last claim wins). Resolved live, never trusted: a presence unit that has exited reads as
@@ -65,6 +71,42 @@ interface AgentRecord {
    * stays inert until re-claimed. Independent of the hub's `mainPane` (the human's read-pane). */
   presence?: string;
 }
+/** A registered project: one git repository, shared by its default checkout and every linked
+ * worktree of it. Keyed by its git common dir, never by a pane or a display name. */
+interface ProjectRecord {
+  /** Stable reference derived from the canonical git common dir (`project.ts`). */
+  id: string;
+  /** Display name — the default checkout's directory basename. Not unique; never a key. */
+  name: string;
+  /** The default checkout's root. */
+  root: string;
+  /** The canonical (realpath) git common dir the id is derived from. */
+  commonDir: string;
+  registeredAt: string;
+}
+/** A project service's ownership lease (`service.ts`) — who authoritatively owns the service now,
+ * persisted independently of any runtime so ownership survives the runtime that held it. */
+interface ServiceLease {
+  project: string;
+  service: string;
+  /** The service endpoint's record id — the durable mailbox and the stable reference. */
+  endpoint: string;
+  /** Fencing generation: bumped on every change of authority (a new reservation or a handoff), so a
+   * runtime holding an older generation is provably stale. */
+  generation: number;
+  /** `vacant` — no owner, no start in progress. `reserved` — a start is in progress (or failed and
+   * not yet expired). `active` — `holder` owns the service at `generation`. */
+  state: 'vacant' | 'reserved' | 'active';
+  holder?: string;
+  reservation?: {
+    token: string;
+    by?: string;
+    at: string;
+    expiresAt: string;
+    forced?: boolean;
+  };
+  updatedAt: string;
+}
 interface InboxSnapshot {
   unread: Message[];
   read: Message[];
@@ -90,6 +132,14 @@ interface Store {
   listAgents(): AgentRecord[];
   removeAgent(id: string): void;
   removeAgentData(id: string): void;
+  /** Upsert a project record (keyed by `rec.id`). */
+  putProject(rec: ProjectRecord): void;
+  getProject(id: string): ProjectRecord | undefined;
+  listProjects(): ProjectRecord[];
+  /** Upsert a service lease (keyed by `lease.project` + `lease.service`). Callers mutate a lease only
+   * while holding that service's named lock (`service.ts`). */
+  putServiceLease(lease: ServiceLease): void;
+  getServiceLease(project: string, service: string): ServiceLease | undefined;
   putPaneIndex(pane: string, agentId: string): void;
   resolvePaneId(pane: string): string | undefined;
   /** Reverse-lookup: an agent's pane from the index, when the agent record itself carries none
@@ -103,6 +153,15 @@ interface Store {
   setMainPane(pane: string | null): void;
   /** The hub's currently bound main pane, or undefined when none is bound. */
   getMainPane(): string | undefined;
+  /** Run `fn` while holding an exclusive, named advisory lock scoped to this store's root —
+   * mutual exclusion for a genuine read-modify-write (read current state, decide, write back),
+   * which an atomic single-file write alone can't make safe against a concurrent racer. Blocks
+   * until acquired or throws `LockTimeoutError` (`store/lock.ts`) after a bounded wait; never
+   * steals a lock a live holder still holds — only one abandoned by a confirmed-dead process.
+   * `setMainPane` uses this internally; callers doing their own load-mutate-save against this
+   * store (e.g. a standing record's presence rebind) should hold the SAME named lock around that
+   * whole sequence, not just around the final write. */
+  withLock<T>(name: string, fn: () => T): T;
 }
 //#endregion
 //#region src/identity.d.ts
@@ -202,18 +261,33 @@ interface DecommissionInput {
   id: string;
   /** Discard uncommitted changes in the worktree. Never overrides refusing the primary checkout. */
   force?: boolean;
+  /**
+   * Reap the unit but leave its worktree on disk, so a pool can detach it and hand it to the next
+   * unit — far cheaper than a fresh checkout per unit. Never overrides refusing the primary
+   * checkout: that guard is about identity, not destructiveness.
+   */
+  keepWorktree?: boolean;
 }
 interface DecommissionResult {
   agent: AgentRecord;
   worktreeRoot?: string;
+  /**
+   * The worktree left on disk by `keepWorktree` — set only when a worktree was actually there to
+   * keep, so a pool manager can treat its presence as "this path is reusable" rather than
+   * re-checking `worktreeRoot` against disk.
+   */
+  retainedWorktree?: string;
   pane?: string;
 }
 /**
  * Tear a unit down and reap its registry record — the deterministic inverse of `spawn`. Refuses
- * the primary checkout (absolute — `--force` never overrides it) and a dirty worktree unless
- * `--force`. Teardown always precedes reap: an already-gone worktree or pane is tolerated, but a
- * genuine worktree-removal failure aborts and leaves the record intact so the operation is
- * retryable.
+ * the primary checkout (absolute — neither `--force` nor `--keep-worktree` overrides it) and a
+ * dirty worktree unless `--force`. Teardown always precedes reap: an already-gone worktree or pane
+ * is tolerated, but a genuine worktree-removal failure aborts and leaves the record intact so the
+ * operation is retryable.
+ *
+ * `keepWorktree` reaps everything else — pane, record, pane pointer, brief — and leaves the
+ * checkout on disk, reporting it as `retainedWorktree`.
  */
 declare function decommission(ctx: IdContext, input: DecommissionInput): DecommissionResult;
 //#endregion
@@ -364,7 +438,177 @@ declare const paths: {
   dataDir: (root: string, id: string) => string;
   briefFile: (root: string, id: string) => string;
   mainPaneFile: (root: string) => string;
+  projectsDir: (root: string) => string;
+  serviceLeaseFile: (root: string, project: string, service: string) => string;
+  projectFile: (root: string, id: string) => string;
+  /** A message's file path within `toId`'s unread/read inbox dir, keyed by its own collision-free
+   * id — validated the same as an agent id (it's the same class of risk: a peer- or CLI-controlled
+   * string becoming a filename). */
+  messageFile: (root: string, toId: string, msgId: string) => string;
+  messageReadFile: (root: string, toId: string, msgId: string) => string;
+};
+//#endregion
+//#region src/project.d.ts
+interface ProjectContext {
+  store: Store;
+  exec?: Exec;
+  now?: () => number;
+}
+/**
+ * Register (or idempotently refresh) the project containing `dir` — any checkout of it, default or
+ * linked. Keeps the first `registeredAt`, so re-registering from a worktree is a no-op in effect.
+ */
+declare function registerProject(ctx: ProjectContext, input?: {
+  dir?: string;
+}): ProjectRecord;
+declare function listProjects(store: Store): ProjectRecord[];
+/**
+ * Resolve a project from anywhere — by id, by a path inside any of its checkouts, or by name when
+ * exactly one registered project carries it. A path registers its project on first use: git has
+ * already confirmed it is a repository, and registering is idempotent, so there is nothing a typo
+ * could mint. A name never registers — nothing can be found by a name no checkout has reported —
+ * and an ambiguous name names its candidates rather than picking one.
+ */
+declare function resolveProject(ctx: ProjectContext, ref: string): ProjectRecord;
+//#endregion
+//#region src/service.d.ts
+interface ServiceContext extends IdContext {
+  /** Whether a unit's session is still there. Defaults to asking its multiplexer (`sessionLive`). */
+  isLive?: (unit: AgentRecord) => boolean;
+}
+type ServiceHealth = 'vacant' | 'starting' | 'expired' | 'healthy' | 'unhealthy';
+interface ServiceView {
+  project: ProjectRecord;
+  endpoint: AgentRecord;
+  lease: ServiceLease;
+  /** The owning unit's record, when the lease is active and the record still exists. */
+  owner?: AgentRecord;
+  health: ServiceHealth;
+  /** Whether the owner's session can be controlled (focused, nudged, read) — `pane` when it has a
+   * multiplexer pane, `none` otherwise. Resolving the address never implies control. */
+  control: 'pane' | 'none';
+  /** A human-readable qualification of `health`/`control`, when there is one. */
+  note?: string;
+}
+type AcquireResult = {
+  outcome: 'resolved';
+  lease: ServiceLease;
+  view: ServiceView;
+} | {
+  outcome: 'starting';
+  lease: ServiceLease;
+  view: ServiceView;
+} | {
+  outcome: 'reserved';
+  lease: ServiceLease;
+  view: ServiceView;
+  token: string;
 };
+type OwnershipErrorCode = 'stale' | 'unit-not-live' | 'unknown-unit';
+/** A refused ownership transition. `stale` means the caller's generation, token, or holder claim is
+ * not the current one — the caller is not (or no longer) the authority it claims to be. */
+declare class ServiceOwnershipError extends Error {
+  readonly code: OwnershipErrorCode;
+  constructor(code: OwnershipErrorCode, message: string);
+}
+/** How long a reservation holds before another caller may take over a start that never bound. */
+declare const DEFAULT_RESERVATION_TTL_MS: number;
+declare function serviceEndpointId(projectId: string, name: string): string;
+/** Read a service's ownership without changing anything. Throws for a service never started. */
+declare function resolveService(ctx: ServiceContext, projectRef: string, name: string): ServiceView;
+interface AcquireInput {
+  /** Who is starting the service — recorded on the reservation for diagnosis. */
+  by?: string;
+  ttlMs?: number;
+  /** Replace even a healthy owner or an unexpired reservation. Must name the current generation, so
+   * a force decided on a stale read fails instead of displacing an owner the caller never saw. */
+  force?: {
+    generation: number;
+  };
+}
+/**
+ * Contact-or-start: resolve the service's healthy owner, or reserve the right to start one. Exactly
+ * one of any number of concurrent callers gets `reserved`; the rest see `starting` (a start is in
+ * progress) or `resolved`. A vacant service, an unhealthy owner, and an expired reservation are all
+ * reservable, each under a new generation that fences out whatever held the old one.
+ */
+declare function acquireService(ctx: ServiceContext, projectRef: string, name: string, input?: AcquireInput): AcquireResult;
+/**
+ * Complete a reservation: make `unit` the owner at the reserved generation. Refused when the
+ * reservation is no longer the current one (it expired and someone else re-reserved, or it was
+ * released) — the starter then holds a runtime that is not the authority and must stop it. A
+ * reservation that expired with nobody taking over is still bindable: nothing replaced it.
+ */
+declare function bindService(ctx: ServiceContext, projectRef: string, name: string, input: {
+  generation: number;
+  token: string;
+  unit: string;
+}): ServiceView;
+/**
+ * Give the service up: abandon a reservation (a failed start — pass its `token`) or step down as
+ * owner (pass the holder `unit`). Either must match the current generation. The generation is kept;
+ * the next acquire bumps it.
+ */
+declare function releaseService(ctx: ServiceContext, projectRef: string, name: string, input: {
+  generation: number;
+  token?: string;
+  unit?: string;
+}): ServiceView;
+/**
+ * Transfer ownership from the current holder to another live unit, under a new generation. Only the
+ * holder at the current generation can hand off, and afterwards it is stale.
+ */
+declare function handoffService(ctx: ServiceContext, projectRef: string, name: string, input: {
+  generation: number;
+  from: string;
+  to: string;
+}): ServiceView;
+/**
+ * The fencing check: succeed only when `unit` owns the service at exactly `generation`. A runtime
+ * calls this before acting as the service's authority; a stale runtime — replaced, handed off, or
+ * recovered past — is refused.
+ */
+declare function verifyOwnership(ctx: ServiceContext, projectRef: string, name: string, input: {
+  unit: string;
+  generation: number;
+}): ServiceView;
+/**
+ * Run `fn` as the verified owner, holding the service lock so no transition can interleave between
+ * the check and the act. For short critical sections only — the lock is bounded-wait for everyone
+ * else — and never reentrant: `fn` must not call another service transition on the same service.
+ */
+declare function withOwnership<T>(ctx: ServiceContext, projectRef: string, name: string, input: {
+  unit: string;
+  generation: number;
+}, fn: (view: ServiceView) => T): T;
+interface StartInput<T extends {
+  unit: string;
+}> extends AcquireInput {
+  /** Launch the runtime that will own the service, returning its unit id. Called only by the one
+   * caller holding the reservation; `generation` is the generation that runtime will own at. */
+  launch: (reservation: {
+    generation: number;
+    endpoint: string;
+  }) => Promise<T>;
+}
+type StartResult<T> = {
+  outcome: 'resolved' | 'starting';
+  view: ServiceView;
+} | {
+  outcome: 'started';
+  view: ServiceView;
+  launched: T;
+};
+/**
+ * Resolve-or-start end to end: acquire, and only when this caller wins the reservation, launch a
+ * runtime and bind it. A launch that throws releases the reservation (best-effort — an expiry covers
+ * a release that itself fails) so the start is retryable at once. A launch that finishes after its
+ * reservation was superseded is refused at bind: the launched unit is not the owner, and the error
+ * names it so the caller can stop it.
+ */
+declare function startService<T extends {
+  unit: string;
+}>(ctx: ServiceContext, projectRef: string, name: string, input: StartInput<T>): Promise<StartResult<T>>;
 //#endregion
 //#region src/session.d.ts
 interface SpawnInput {
@@ -445,6 +689,11 @@ declare class FileStore implements Store {
   listAgents(): AgentRecord[];
   removeAgent(id: string): void;
   removeAgentData(id: string): void;
+  putProject(rec: ProjectRecord): void;
+  getProject(id: string): ProjectRecord | undefined;
+  listProjects(): ProjectRecord[];
+  putServiceLease(lease: ServiceLease): void;
+  getServiceLease(project: string, service: string): ServiceLease | undefined;
   putPaneIndex(pane: string, agentId: string): void;
   resolvePaneId(pane: string): string | undefined;
   findPaneByAgentId(agentId: string): string | undefined;
@@ -453,6 +702,7 @@ declare class FileStore implements Store {
   readBrief(agentId: string): string | undefined;
   setMainPane(pane: string | null): void;
   getMainPane(): string | undefined;
+  withLock<T>(name: string, fn: () => T): T;
 }
 //#endregion
 //#region src/wake/await.d.ts
@@ -507,4 +757,4 @@ interface WatchOptions {
  */
 declare function watchMail(ctx: MsgContext, input: WatchInput, onMessage: (msg: InboxItem) => void, opts?: WatchOptions): Promise<void>;
 //#endregion
-export { type AgentDef, type AgentRecord, type AwaitInput, type AwaitOutcome, type DecommissionInput, type DecommissionResult, type Exec, FileStore, type Format, type Harness, type HookEvent, type IdContext, type InboxItem, type InboxQuery, type InboxSnapshot, type Message, type MuxProbe, type RegisterInput, type RootOptions, type SendInput, type SpawnInput, type SpawnResult, type Store, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, spawnAndWake, toonList, toonObject, touch, watchMail };
+export { type AcquireInput, type AcquireResult, type AgentDef, type AgentRecord, type AwaitInput, type AwaitOutcome, DEFAULT_RESERVATION_TTL_MS, type DecommissionInput, type DecommissionResult, type Exec, FileStore, type Format, type Harness, type HookEvent, type IdContext, type InboxItem, type InboxQuery, type InboxSnapshot, type Message, type MuxProbe, type OwnershipErrorCode, type ProjectContext, type ProjectRecord, type RegisterInput, type RootOptions, type SendInput, type ServiceContext, type ServiceHealth, type ServiceLease, ServiceOwnershipError, type ServiceView, type SpawnInput, type SpawnResult, type StartInput, type StartResult, type Store, ack, acquireService, assertDistinctFromPrimary, awaitReply, bindService, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, handoffService, inbox, injectInbox, install, listAgentDefs, listAgents, listProjects, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, registerProject, releaseService, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProject, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, resolveService, selectSessionAdapter, send, serviceEndpointId, spawn, spawnAndWake, startService, toonList, toonObject, touch, verifyOwnership, watchMail, withOwnership };