@aperant/framework 0.6.2

package/dist/cli/coordination/agent-identity.mjs

@@ -0,0 +1,94 @@
+/**
+ * @internal
+ * agent-identity.mjs — per-agent identity record (R4 precursor).
+ *
+ * This module is part of the @internal CoordinationStore seam (R8). Do NOT
+ * import from `bin/apt-tools.mjs` or add to any package `exports` map.
+ *
+ * V1 returns `{ agentId, pid, hostname, incarnation }` — enough for the
+ * team-status directory in R2 to key per-agent files. R4 (subtask 6) fills in
+ * TTL-based liveness filtering on top of this record.
+ *
+ * Incarnation is a monotonic counter stored at
+ * `.aperant/team-status/.incarnation`. Incremented once per process via
+ * `nextIncarnation(projectRoot)` during identity resolution and cached in
+ * module scope so repeated calls within the same process are stable.
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { hostname as osHostname } from 'node:os';
+import { join } from 'node:path';
+import { detectWorktree } from '../git/worktree-detect.mjs';
+import { withFileLock } from '../util/fs-lock.mjs';
+import { atomicWriteJson } from '../util/io.mjs';
+// Cached identity per project root (rooted at the shared .aperant/ dir).
+const cache = new Map();
+/**
+ * Resolve the shared coordination root — always the main repo's root, even
+ * when called from a worktree. Mirrors commands/event.mjs.
+ */
+export function resolveSharedRoot(projectDir) {
+    const wt = detectWorktree(projectDir);
+    return wt.is_worktree && wt.main_repo_root ? wt.main_repo_root : projectDir;
+}
+/**
+ * Read and increment the per-project incarnation counter atomically. Stored
+ * as JSON `{ value: <int> }` under `.aperant/team-status/.incarnation` so the
+ * normal atomicWriteJson pipeline handles it.
+ *
+ * If the counter file is missing/malformed, we start from 1.
+ */
+function nextIncarnation(projectRoot) {
+    const sharedRoot = resolveSharedRoot(projectRoot);
+    const dir = join(sharedRoot, '.aperant', 'team-status');
+    mkdirSync(dir, { recursive: true });
+    const counterPath = join(dir, '.incarnation');
+    let next = 1;
+    withFileLock(counterPath, () => {
+        let current = 0;
+        if (existsSync(counterPath)) {
+            try {
+                const raw = readFileSync(counterPath, 'utf-8').trim();
+                const parsed = JSON.parse(raw);
+                if (typeof parsed?.value === 'number' && Number.isFinite(parsed.value)) {
+                    current = parsed.value;
+                }
+            }
+            catch {
+                /* malformed — restart from 0 */
+            }
+        }
+        next = current + 1;
+        atomicWriteJson(counterPath, { value: next });
+    }, { projectRoot: sharedRoot });
+    return next;
+}
+/**
+ * Return the current agent's identity. Cached per project root so repeated
+ * callers within a single process see a stable incarnation.
+ *
+ * `APT_AGENT_ID` overrides the default `<hostname>-<pid>` assembly — used by
+ * tests to force a deterministic id.
+ */
+export function getAgentIdentity(projectDir) {
+    const sharedRoot = resolveSharedRoot(projectDir);
+    if (cache.has(sharedRoot))
+        return cache.get(sharedRoot);
+    const pid = process.pid;
+    const host = osHostname();
+    const agentId = process.env.APT_AGENT_ID || `${host}-${pid}`;
+    const incarnation = nextIncarnation(projectDir);
+    const identity = { agentId, pid, hostname: host, incarnation };
+    cache.set(sharedRoot, identity);
+    return identity;
+}
+/**
+ * Test-only helper: reset the process-local identity cache so a fresh
+ * getAgentIdentity() call picks up a new incarnation. Not part of the public
+ * surface.
+ *
+ * @internal
+ */
+export function __resetAgentIdentityCacheForTests() {
+    cache.clear();
+}
+//# sourceMappingURL=agent-identity.mjs.map

package/dist/cli/coordination/agent-identity.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-identity.mjs","sourceRoot":"","sources":["../../../src/cli/coordination/agent-identity.mjs"],"names":[],"mappings":"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"}

package/dist/cli/coordination/event-log.d.mts

@@ -0,0 +1,37 @@
+/**
+ * Append a lifecycle event. `evt` shape:
+ *   {
+ *     op: 'task.created' | 'task.lifecycle.{phase}' | 'task.closed' | ...,
+ *     task: string,                // task id
+ *     data?: object,               // op-specific payload
+ *   }
+ *
+ * The writer stamps `t`, `agent`, `pid`, `hostname`, `incarnation` onto the
+ * record so consumers can correlate across machines without fetching state.
+ *
+ * `projectRoot` may be a worktree path; the writer resolves the shared main
+ * repo root so every agent's events land in a single directory.
+ *
+ * @internal
+ */
+export function appendLifecycleEvent(projectRoot: any, evt: any, now?: Date): {
+    file: string;
+    record: {
+        t: string;
+        agent: any;
+        pid: any;
+        hostname: any;
+        incarnation: any;
+        op: any;
+        task: any;
+        data: any;
+    };
+};
+/**
+ * Read all events for a given day bucket (defaults to today, UTC). Returns
+ * an array of parsed objects; malformed lines are skipped defensively.
+ *
+ * @internal
+ */
+export function readLifecycleEventsForDay(projectRoot: any, day?: string): any[];
+//# sourceMappingURL=event-log.d.mts.map

package/dist/cli/coordination/event-log.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.d.mts","sourceRoot":"","sources":["../../../src/cli/coordination/event-log.mjs"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;GAeG;AACH;;;;;;;;;;;;EAgBC;AAED;;;;;GAKG;AACH,iFAeC"}

package/dist/cli/coordination/event-log.mjs

@@ -0,0 +1,88 @@
+/**
+ * @internal
+ * event-log.mjs — append-only lifecycle event log (R10).
+ *
+ * Writes one JSON-encoded line per event to
+ * `.aperant/events/{YYYY-MM-DD}.jsonl` via the R3 appendJsonl primitive.
+ * POSIX O_APPEND gives us atomic concurrent writes across agents, so
+ * multiple processes running `task update` / `task close` cannot tear each
+ * other's lines.
+ *
+ * This module is `@internal` — consumed only through the CoordinationStore
+ * seam (store.appendEvent). Do NOT import from bin/apt-tools.mjs.
+ *
+ * The existing numbered-JSON event surface in commands/event.mjs is NOT
+ * touched — its `rebuild-state` consumer keeps working. The JSONL log is
+ * additive, covering the forensic trail the roundtable's Devil's Advocate
+ * required for when state.json / team-status leave git (R2, R6).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { appendJsonl } from '../util/io.mjs';
+import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs';
+/**
+ * Derive the day bucket for the current instant. UTC so agents on different
+ * machines agree on the file name.
+ */
+function todayBucket(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/**
+ * Append a lifecycle event. `evt` shape:
+ *   {
+ *     op: 'task.created' | 'task.lifecycle.{phase}' | 'task.closed' | ...,
+ *     task: string,                // task id
+ *     data?: object,               // op-specific payload
+ *   }
+ *
+ * The writer stamps `t`, `agent`, `pid`, `hostname`, `incarnation` onto the
+ * record so consumers can correlate across machines without fetching state.
+ *
+ * `projectRoot` may be a worktree path; the writer resolves the shared main
+ * repo root so every agent's events land in a single directory.
+ *
+ * @internal
+ */
+export function appendLifecycleEvent(projectRoot, evt, now = new Date()) {
+    const sharedRoot = resolveSharedRoot(projectRoot);
+    const identity = getAgentIdentity(projectRoot);
+    const file = join(sharedRoot, '.aperant', 'events', `${todayBucket(now)}.jsonl`);
+    const record = {
+        t: now.toISOString(),
+        agent: identity.agentId,
+        pid: identity.pid,
+        hostname: identity.hostname,
+        incarnation: identity.incarnation,
+        op: evt.op,
+        task: evt.task ?? null,
+        data: evt.data ?? {},
+    };
+    appendJsonl(file, record);
+    return { file, record };
+}
+/**
+ * Read all events for a given day bucket (defaults to today, UTC). Returns
+ * an array of parsed objects; malformed lines are skipped defensively.
+ *
+ * @internal
+ */
+export function readLifecycleEventsForDay(projectRoot, day = todayBucket()) {
+    const sharedRoot = resolveSharedRoot(projectRoot);
+    const file = join(sharedRoot, '.aperant', 'events', `${day}.jsonl`);
+    if (!existsSync(file))
+        return [];
+    const body = readFileSync(file, 'utf-8');
+    const out = [];
+    for (const line of body.split('\n')) {
+        if (!line)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=event-log.mjs.map

package/dist/cli/coordination/event-log.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.mjs","sourceRoot":"","sources":["../../../src/cli/coordination/event-log.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAE1E;;;GAGG;AACH,SAAS,WAAW,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACpC,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IACtE,MAAM,UAAU,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAA;IACjD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAA;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAChF,MAAM,MAAM,GAAG;QACd,CAAC,EAAE,GAAG,CAAC,WAAW,EAAE;QACpB,KAAK,EAAE,QAAQ,CAAC,OAAO;QACvB,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;QACtB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;KACpB,CAAA;IACD,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACzB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAW,EAAE,GAAG,GAAG,WAAW,EAAE;IACzE,MAAM,UAAU,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAA;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,GAAG,QAAQ,CAAC,CAAA;IACnE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAChC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACxC,MAAM,GAAG,GAAG,EAAE,CAAA;IACd,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,SAAQ;QACnB,IAAI,CAAC;YACJ,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACR,oBAAoB;QACrB,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC"}

package/dist/cli/coordination/store.d.mts

@@ -0,0 +1,58 @@
+/**
+ * Construct a coordination store bound to a specific project root. The
+ * returned object is plain-JS with bound methods — no classes, matching the
+ * rest of the `.mjs` CLI kernel style.
+ *
+ * @internal
+ */
+export function createCoordinationStore(projectRoot: any): {
+    /** @internal */
+    resolveSharedRoot: () => any;
+    /** @internal — returns null if state.json is missing or malformed. */
+    readState(): any;
+    /**
+     * @internal — lock-protected atomic write of the full state object.
+     * Prefer `updateState(mutator)` for read-modify-write.
+     */
+    writeState(state: any): void;
+    /**
+     * @internal — read, mutate via `mutator(state)`, write back under a
+     * single lock. Mirrors the pattern used throughout commands/task.mjs.
+     */
+    updateState(mutator: any): any;
+    /**
+     * @internal — R2: per-agent team-status/{agentId}.json writes.
+     * C34: the legacy active.json dual-write has been removed; the
+     * per-agent directory is the sole source of truth.
+     */
+    upsertTeamStatus(taskId: any, data?: {}): void;
+    /** @internal — see upsertTeamStatus. */
+    removeTeamStatus(taskId: any): void;
+    /**
+     * @internal — R2 directory aggregation + R4 liveness filtering.
+     * Pass `{ includeStale: true }` to disable stale-filtering (used by
+     * `apt-tools active list --include-stale`).
+     */
+    listTeamStatus(opts?: {}): any[];
+    /**
+     * @internal — R10 append-only event log. Emits one JSONL line per
+     * call via appendLifecycleEvent. Best-effort: filesystem errors are
+     * swallowed so a missing events/ dir never breaks task lifecycle.
+     */
+    appendEvent(evt: any): {
+        file: string;
+        record: {
+            t: string;
+            agent: any;
+            pid: any;
+            hostname: any;
+            incarnation: any;
+            op: any;
+            task: any;
+            data: any;
+        };
+    } | null;
+    /** @internal */
+    getIdentity(): any;
+};
+//# sourceMappingURL=store.d.mts.map

package/dist/cli/coordination/store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.mts","sourceRoot":"","sources":["../../../src/cli/coordination/store.mjs"],"names":[],"mappings":"AAwCA;;;;;;GAMG;AACH;IAKE,gBAAgB;;IAGhB,sEAAsE;;IAUtE;;;OAGG;;IAWH;;;OAGG;;IAqBH;;;;OAIG;;IAKH,wCAAwC;;IAKxC;;;;OAIG;;IAKH;;;;OAIG;;;;;;;;;;;;;;IAUH,gBAAgB;;EAKjB"}

package/dist/cli/coordination/store.mjs

@@ -0,0 +1,129 @@
+/**
+ * @internal
+ * coordination/store.mjs — thin abstraction seam for coordination writes (R8).
+ *
+ * IMPORTANT: this module is `@internal`. It is NOT exported from
+ * `bin/apt-tools.mjs`, it is NOT added to any package `exports` map, and it
+ * must not appear in README / public docs. The seam exists so future
+ * subtasks (R2 team-status dir, R4 liveness, R10 event log) have a single
+ * place to swap implementations without every call site needing an edit.
+ *
+ * V1 contract: every method is a thin wrapper over the existing filesystem
+ * helpers (`atomicWriteJson`, `withFileLock`). Behavior must match the
+ * pre-seam call sites byte-for-byte — C29's smoke-drain harness (retired in
+ * C30) originally guarded against regressions; the vitest suite under
+ * src/__tests__ now owns that coverage.
+ *
+ * Methods:
+ *   - readState()
+ *   - writeState(next) / updateState(mutator)
+ *   - upsertTeamStatus(taskId, data) / removeTeamStatus(taskId)
+ *   - listTeamStatus({ includeStale? })            — filled in by R2
+ *   - appendEvent(evt)                             — filled in by R10
+ *   - resolveSharedRoot()                          — main repo root helper
+ *
+ * Callers that mutate state should use `updateState(mutator)` (lock-protected
+ * read-modify-write). Callers that only read should use `readState()`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { withFileLock } from '../util/fs-lock.mjs';
+import { atomicWriteJson } from '../util/io.mjs';
+import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs';
+import { appendLifecycleEvent } from './event-log.mjs';
+import { listActive as teamStatusListActive, removeSelf as teamStatusRemoveSelf, upsertSelf as teamStatusUpsertSelf, } from './team-status.mjs';
+/**
+ * Construct a coordination store bound to a specific project root. The
+ * returned object is plain-JS with bound methods — no classes, matching the
+ * rest of the `.mjs` CLI kernel style.
+ *
+ * @internal
+ */
+export function createCoordinationStore(projectRoot) {
+    const sharedRoot = resolveSharedRoot(projectRoot);
+    const statePath = join(sharedRoot, '.aperant', 'state.json');
+    return {
+        /** @internal */
+        resolveSharedRoot: () => sharedRoot,
+        /** @internal — returns null if state.json is missing or malformed. */
+        readState() {
+            if (!existsSync(statePath))
+                return null;
+            try {
+                return JSON.parse(readFileSync(statePath, 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        },
+        /**
+         * @internal — lock-protected atomic write of the full state object.
+         * Prefer `updateState(mutator)` for read-modify-write.
+         */
+        writeState(state) {
+            withFileLock(statePath, () => {
+                atomicWriteJson(statePath, state);
+            }, { projectRoot: sharedRoot });
+        },
+        /**
+         * @internal — read, mutate via `mutator(state)`, write back under a
+         * single lock. Mirrors the pattern used throughout commands/task.mjs.
+         */
+        updateState(mutator) {
+            return withFileLock(statePath, () => {
+                let state = null;
+                if (existsSync(statePath)) {
+                    try {
+                        state = JSON.parse(readFileSync(statePath, 'utf-8'));
+                    }
+                    catch {
+                        state = null;
+                    }
+                }
+                const result = mutator(state);
+                if (result !== undefined)
+                    atomicWriteJson(statePath, result);
+                return result;
+            }, { projectRoot: sharedRoot });
+        },
+        /**
+         * @internal — R2: per-agent team-status/{agentId}.json writes.
+         * C34: the legacy active.json dual-write has been removed; the
+         * per-agent directory is the sole source of truth.
+         */
+        upsertTeamStatus(taskId, data = {}) {
+            teamStatusUpsertSelf(projectRoot, taskId, data);
+        },
+        /** @internal — see upsertTeamStatus. */
+        removeTeamStatus(taskId) {
+            teamStatusRemoveSelf(projectRoot, taskId);
+        },
+        /**
+         * @internal — R2 directory aggregation + R4 liveness filtering.
+         * Pass `{ includeStale: true }` to disable stale-filtering (used by
+         * `apt-tools active list --include-stale`).
+         */
+        listTeamStatus(opts = {}) {
+            return teamStatusListActive(projectRoot, opts);
+        },
+        /**
+         * @internal — R10 append-only event log. Emits one JSONL line per
+         * call via appendLifecycleEvent. Best-effort: filesystem errors are
+         * swallowed so a missing events/ dir never breaks task lifecycle.
+         */
+        appendEvent(evt) {
+            try {
+                return appendLifecycleEvent(projectRoot, evt);
+            }
+            catch {
+                /* best-effort — never block a lifecycle transition on the log */
+                return null;
+            }
+        },
+        /** @internal */
+        getIdentity() {
+            return getAgentIdentity(projectRoot);
+        },
+    };
+}
+//# sourceMappingURL=store.mjs.map

package/dist/cli/coordination/store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.mjs","sourceRoot":"","sources":["../../../src/cli/coordination/store.mjs"],"names":[],"mappings":"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"}

package/dist/cli/coordination/team-status.d.mts

@@ -0,0 +1,84 @@
+/**
+ * Upsert the current agent's status file. `data` is merged on top of any
+ * existing record so callers can pass partial updates (e.g. a lifecycle-phase
+ * bump without re-asserting owner/branch).
+ *
+ * @internal
+ */
+export function upsertSelf(projectRoot: any, taskId: any, data?: {}): {
+    agentId: any;
+    pid: any;
+    hostname: any;
+    incarnation: any;
+    taskId: any;
+    description: any;
+    owner: any;
+    owner_email: any;
+    branch: any;
+    lifecycle_phase: any;
+    scope: any;
+    progress: any;
+    current_subtask: any;
+    started_at: any;
+    refreshedAt: string;
+    ttlSeconds: any;
+};
+/**
+ * Remove the current agent's file if it currently advertises the given
+ * taskId. No-op if another task is active under this agent (prevents a stale
+ * remove from dropping a newer task's status).
+ *
+ * @internal
+ */
+export function removeSelf(projectRoot: any, taskId: any): boolean;
+/**
+ * Decide whether a team-status entry represents a currently-running agent.
+ *
+ * Same-host semantics (R4):
+ *   - Live iff `process.kill(pid, 0)` succeeds AND the stored incarnation
+ *     matches ANY known live counter value for this host. Since we can only
+ *     verify the current process's incarnation, the cheap heuristic is:
+ *     "same-host + kill signal survives" — if the PID is still alive on this
+ *     machine, it belongs to us (or to another framework process that is
+ *     legitimately tracking the task). PID reuse is bounded by the incarnation
+ *     counter: a stale entry with a recycled PID will have a lower incarnation
+ *     than the current counter, so we reject it.
+ *   - We treat entries with missing pid/incarnation (e.g. legacy migrations)
+ *     as live iff they have a fresh refreshedAt — otherwise they get
+ *     stale-filtered through the TTL path.
+ *
+ * Cross-host semantics:
+ *   - Live iff `now - refreshedAt < ttlSeconds*1000 + TTL_SKEW_MS`.
+ *
+ * @internal
+ */
+export function isAlive(entry: any, opts?: {}): boolean;
+/**
+ * List team-status entries. By default filters out dead/stale records via
+ * `isAlive`. Pass `{ includeStale: true }` to get every parseable file
+ * (debugging surface — exposed via `apt-tools active list --include-stale`).
+ *
+ * C34: the one-shot active.json migration has been removed. An empty
+ * directory just returns [].
+ *
+ * @internal
+ */
+export function listActive(projectRoot: any, opts?: {}): any[];
+/**
+ * Helper for tests and diagnostics — never called from lifecycle code.
+ * @internal
+ */
+export function __debugDir(projectRoot: any): string;
+/**
+ * Helper for readers that need to project to the shape consumers of
+ * `active.json` expected. Preserves keys so commands/active.mjs output stays
+ * stable after the cutover.
+ *
+ * @internal
+ */
+export function toActiveBoardShape(entries: any): {
+    version: number;
+    active: {};
+    updated_at: string;
+};
+//# sourceMappingURL=team-status.d.mts.map

package/dist/cli/coordination/team-status.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-status.d.mts","sourceRoot":"","sources":["../../../src/cli/coordination/team-status.mjs"],"names":[],"mappings":"AA0CA;;;;;;GAMG;AACH;;;;;;;;;;;;;;;;;EAuDC;AAED;;;;;;GAMG;AACH,mEAgBC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wDAgCC;AAED;;;;;;;;;GASG;AACH,+DA8BC;AAED;;;GAGG;AACH,qDAEC;AAED;;;;;;GAMG;AACH;;;;EA0BC"}