@aperant/framework 0.10.0 → 0.12.0

package/dist/cli/coordination/catch-up.mjs

@@ -0,0 +1,239 @@
+/**
+ * @internal
+ * coordination/catch-up.mjs — composes the combined catch-up panel: the
+ * Welcome-Back Summary (your own half-finished work, local-only) and the
+ * gated Team-Change Digest (what teammates merged while you were away).
+ *
+ * Composition order is fixed: welcome_back first, then team_digest (LD-10).
+ * The renderer (apt/SKILL.md) enforces display order; this module only sets
+ * the field order on the returned object.
+ *
+ * Both halves diff against one Last-Seen Marker:
+ *   - Welcome-Back fires on a staleness threshold (now - last_run_at), reads
+ *     only local state.active_tasks, and is ALWAYS-ON regardless of visibility
+ *     (LD-08/09).
+ *   - Team-Change Digest fires only when share.visibility is team/oss AND the
+ *     local default-branch sha has moved since last_main_sha (LD-04/06/07).
+ *
+ * Returns null when neither half fires. This module is `@internal` — reached
+ * via the route.mjs lazy-compute path and the apt-tools catch-up command, not
+ * from bin/apt-tools.mjs directly.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveSharePolicy } from '../config/share-policy.mjs';
+import { listMergedPullRequests } from '../git/default-branch.mjs';
+import { getGitIdentity } from '../git/identity.mjs';
+import { resolveSharedRoot } from './agent-identity.mjs';
+const HOUR_MS = 60 * 60 * 1000;
+/**
+ * Best-available per-task activity timestamp (ms). Prefers an explicit
+ * updated_at, then the most recent history entry, then created_at.
+ *
+ * @param {object} task
+ * @returns {number} epoch ms, or 0 when no timestamp is parseable.
+ */
+function taskActivityMs(task) {
+    const candidates = [];
+    if (task?.updated_at)
+        candidates.push(Date.parse(task.updated_at));
+    if (Array.isArray(task?.history)) {
+        for (const h of task.history) {
+            if (h?.at)
+                candidates.push(Date.parse(h.at));
+        }
+    }
+    if (task?.created_at)
+        candidates.push(Date.parse(task.created_at));
+    const valid = candidates.filter((n) => Number.isFinite(n));
+    return valid.length ? Math.max(...valid) : 0;
+}
+/**
+ * A coarse "x ago" relative-time string. Kept dependency-free and stable for
+ * tests — granularity is minutes/hours/days.
+ *
+ * @param {number} deltaMs
+ * @returns {string}
+ */
+function relativeTime(deltaMs) {
+    if (!Number.isFinite(deltaMs) || deltaMs < 0)
+        return 'just now';
+    const mins = Math.floor(deltaMs / 60000);
+    if (mins < 1)
+        return 'just now';
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+/**
+ * Read the first actionable next-step line from a task's CONTINUE note, if one
+ * exists at `.aperant/tasks/{taskId}/CONTINUE.md`. Parses the first non-empty
+ * item under the `## Next Steps` heading (the pause-note format).
+ *
+ * @param {string} sharedRoot
+ * @param {string} taskId
+ * @returns {string|null}
+ */
+function readNextStepLine(sharedRoot, taskId) {
+    if (!taskId)
+        return null;
+    const notePath = join(sharedRoot, '.aperant', 'tasks', taskId, 'CONTINUE.md');
+    if (!existsSync(notePath))
+        return null;
+    let text;
+    try {
+        text = readFileSync(notePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const lines = text.split('\n');
+    const headingIdx = lines.findIndex((l) => /^##\s+Next Steps\s*$/i.test(l.trim()));
+    if (headingIdx === -1)
+        return null;
+    for (let i = headingIdx + 1; i < lines.length; i++) {
+        const raw = lines[i].trim();
+        if (raw.startsWith('##'))
+            break; // next section
+        if (raw.length === 0)
+            continue;
+        // Strip a leading list marker: "1. ", "- ", "* ".
+        const cleaned = raw.replace(/^(\d+\.|[-*])\s+/, '').trim();
+        if (cleaned.length > 0)
+            return cleaned;
+    }
+    return null;
+}
+/**
+ * Build the Welcome-Back half from local state (LD-08/09). Returns null when
+ * the threshold has not elapsed or there is no active task.
+ *
+ * @param {object} params
+ * @param {object} params.config
+ * @param {number} params.now           epoch ms
+ * @param {object|null} params.marker
+ * @param {object|null} params.state    raw state.json (for active_tasks)
+ * @param {string} params.sharedRoot
+ * @returns {object|null}
+ */
+function buildWelcomeBack({ config, now, marker, state, sharedRoot }) {
+    const wb = config?.collaboration?.welcome_back;
+    if (wb?.enabled === false)
+        return null;
+    const lastRunAt = marker?.last_run_at ? Date.parse(marker.last_run_at) : NaN;
+    const thresholdHours = Number.isFinite(wb?.threshold_hours) ? wb.threshold_hours : 16;
+    // Only fire when we have a baseline AND the gap strictly exceeds the threshold.
+    if (!Number.isFinite(lastRunAt))
+        return null;
+    if (now - lastRunAt <= thresholdHours * HOUR_MS)
+        return null;
+    const activeTasks = state?.active_tasks && typeof state.active_tasks === 'object' ? state.active_tasks : {};
+    const ids = Object.keys(activeTasks);
+    if (ids.length === 0)
+        return null;
+    // Pick the single most-recently-active task.
+    let bestId = null;
+    let bestMs = -1;
+    for (const id of ids) {
+        const ms = taskActivityMs(activeTasks[id]);
+        if (ms > bestMs) {
+            bestMs = ms;
+            bestId = id;
+        }
+    }
+    if (!bestId)
+        return null;
+    const task = activeTasks[bestId];
+    const currentSubtask = task?.progress?.current_subtask ?? task?.current_subtask ?? null;
+    return {
+        task_id: bestId,
+        description: task?.description ?? bestId,
+        lifecycle_phase: task?.lifecycle_phase ?? null,
+        current_subtask: currentSubtask,
+        progress: task?.progress ?? null,
+        relative_time: bestMs > 0 ? relativeTime(now - bestMs) : null,
+        next_step: readNextStepLine(sharedRoot, bestId),
+        others_count: Math.max(0, ids.length - 1),
+    };
+}
+/**
+ * Build the Team-Change Digest half (LD-04/06/07). Returns null when the
+ * visibility gate is closed (solo), the digest is disabled, or the
+ * default-branch sha has not moved since the marker.
+ *
+ * @param {object} params
+ * @param {string} params.projectRoot
+ * @param {object} params.config
+ * @param {object|null} params.marker
+ * @param {{ branch: string, sha: string }|null} params.defaultBranch
+ * @returns {object|null}
+ */
+function buildTeamDigest({ projectRoot, config, marker, defaultBranch }) {
+    const td = config?.collaboration?.team_digest;
+    if (td?.enabled === false)
+        return null;
+    const visibility = resolveSharePolicy(config).visibility;
+    if (visibility !== 'team' && visibility !== 'oss')
+        return null;
+    if (!defaultBranch?.sha)
+        return null;
+    // Only fire when main has actually moved since the recorded baseline.
+    if (marker?.last_main_sha && marker.last_main_sha === defaultBranch.sha)
+        return null;
+    const maxEntries = Number.isInteger(td?.max_entries) && td.max_entries > 0 ? td.max_entries : 7;
+    const identity = (() => {
+        try {
+            return getGitIdentity(projectRoot);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const { entries, more_count } = listMergedPullRequests(projectRoot, {
+        sinceSha: marker?.last_main_sha || null,
+        defaultBranch: defaultBranch.branch,
+        currentUserEmail: identity?.email || '',
+        maxEntries,
+    });
+    if (entries.length === 0 && more_count === 0)
+        return null;
+    return { entries, more_count };
+}
+/**
+ * Compose the combined catch-up panel. Returns null when neither half fires.
+ *
+ * @param {string} projectRoot
+ * @param {object} params
+ * @param {object} params.config
+ * @param {number} params.now                       epoch ms
+ * @param {object|null} params.marker               Last-Seen Marker
+ * @param {{ branch: string, sha: string }|null} params.defaultBranch
+ * @returns {{ welcome_back: object|null, team_digest: object|null }|null}
+ *
+ * @internal
+ */
+export function computeCatchUpPanel(projectRoot, { config, now, marker, defaultBranch } = {}) {
+    const sharedRoot = resolveSharedRoot(projectRoot);
+    const state = (() => {
+        const statePath = join(sharedRoot, '.aperant', 'state.json');
+        if (!existsSync(statePath))
+            return null;
+        try {
+            return JSON.parse(readFileSync(statePath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    })();
+    const welcome_back = buildWelcomeBack({ config, now, marker, state, sharedRoot });
+    const team_digest = buildTeamDigest({ projectRoot, config, marker, defaultBranch });
+    if (!welcome_back && !team_digest)
+        return null;
+    // Fixed field order: welcome_back first (LD-10).
+    return { welcome_back, team_digest };
+}
+//# sourceMappingURL=catch-up.mjs.map

package/dist/cli/coordination/catch-up.mjs.map

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

package/dist/cli/coordination/last-seen.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Slug a git email into a filesystem-safe key: lowercase, every run of
+ * non-[a-z0-9] characters collapsed to a single '-'.
+ *
+ * @param {string} email
+ * @returns {string}
+ */
+export function slugFromEmail(email: string): string;
+/**
+ * Read the current user's Last-Seen Marker. Returns null when the git email is
+ * absent (no identity → no key) or the file does not yet exist / is malformed.
+ *
+ * @param {string} projectRoot
+ * @returns {{ last_run_at: string|null, last_main_sha: string|null, last_active_task: string|null }|null}
+ *
+ * @internal
+ */
+export function readLastSeen(projectRoot: string): {
+    last_run_at: string | null;
+    last_main_sha: string | null;
+    last_active_task: string | null;
+} | null;
+/**
+ * Advance the marker, merging partial fields onto any existing record.
+ *
+ * Marker-advance semantics (LD-02):
+ *   - last_run_at is always settable (it measures engagement).
+ *   - last_main_sha is optional — the caller passes it only AFTER the digest
+ *     was computed (even when empty). When undefined, the existing sha is kept.
+ *   - last_active_task is optional — the welcome-back task id, kept otherwise.
+ *
+ * No-op (returns null) when the git email is absent — there is no key to write.
+ *
+ * @param {string} projectRoot
+ * @param {{ last_run_at?: string, last_main_sha?: string|null, last_active_task?: string|null }} fields
+ * @returns {object|null} the written record, or null when there is no identity key.
+ *
+ * @internal
+ */
+export function advanceLastSeen(projectRoot: string, fields?: {
+    last_run_at?: string;
+    last_main_sha?: string | null;
+    last_active_task?: string | null;
+}): object | null;
+//# sourceMappingURL=last-seen.d.mts.map

package/dist/cli/coordination/last-seen.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"last-seen.d.mts","sourceRoot":"","sources":["../../../src/cli/coordination/last-seen.mjs"],"names":[],"mappings":"AAiCA;;;;;;GAMG;AACH,qCAHW,MAAM,GACJ,MAAM,CAOlB;AAgBD;;;;;;;;GAQG;AACH,0CALW,MAAM,GACJ;IAAE,WAAW,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,gBAAgB,EAAE,MAAM,GAAC,IAAI,CAAA;CAAE,GAAC,IAAI,CAkBxG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW,MAAM,WACN;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,GAAC,IAAI,CAAA;CAAE,GACnF,MAAM,GAAC,IAAI,CA+BvB"}

package/dist/cli/coordination/last-seen.mjs

@@ -0,0 +1,128 @@
+/**
+ * @internal
+ * last-seen.mjs — per-machine, per-git-identity Last-Seen Marker (LD-01).
+ *
+ * The collaboration catch-up surfaces (Welcome-Back Summary + Team-Change
+ * Digest) both diff against one baseline record per human/machine:
+ *
+ *   .aperant/last-seen/{email-slug}.json  →  { last_run_at, last_main_sha, last_active_task }
+ *
+ * The slug is derived from the git `user.email` (stable per human/machine),
+ * lowercased with every non-[a-z0-9] run collapsed to '-'. The directory is
+ * gitignored in the same per-machine ephemeral class as `team-status/` and
+ * `events/` (see upgrade-gitignore.mjs / share-policy.mjs).
+ *
+ * Modeled on team-status.mjs: resolveSharedRoot-based path so the marker lives
+ * in the main repo even when called from a worktree; atomicWriteJson +
+ * mkdirSync(recursive) for durable writes.
+ *
+ * This module is `@internal` — consumed only through the CoordinationStore
+ * seam (store.readLastSeen / store.advanceLastSeen). Do NOT import it from
+ * bin/apt-tools.mjs.
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getGitIdentity } from '../git/identity.mjs';
+import { atomicWriteJson } from '../util/io.mjs';
+import { resolveSharedRoot } from './agent-identity.mjs';
+function lastSeenDir(projectRoot) {
+    return join(resolveSharedRoot(projectRoot), '.aperant', 'last-seen');
+}
+/**
+ * Slug a git email into a filesystem-safe key: lowercase, every run of
+ * non-[a-z0-9] characters collapsed to a single '-'.
+ *
+ * @param {string} email
+ * @returns {string}
+ */
+export function slugFromEmail(email) {
+    return String(email)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function markerPath(projectRoot) {
+    const identity = (() => {
+        try {
+            return getGitIdentity(projectRoot);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (!identity?.email)
+        return null;
+    const slug = slugFromEmail(identity.email);
+    if (!slug)
+        return null;
+    return join(lastSeenDir(projectRoot), `${slug}.json`);
+}
+/**
+ * Read the current user's Last-Seen Marker. Returns null when the git email is
+ * absent (no identity → no key) or the file does not yet exist / is malformed.
+ *
+ * @param {string} projectRoot
+ * @returns {{ last_run_at: string|null, last_main_sha: string|null, last_active_task: string|null }|null}
+ *
+ * @internal
+ */
+export function readLastSeen(projectRoot) {
+    const path = markerPath(projectRoot);
+    if (!path || !existsSync(path))
+        return null;
+    try {
+        const record = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!record || typeof record !== 'object')
+            return null;
+        return {
+            last_run_at: record.last_run_at ?? null,
+            last_main_sha: record.last_main_sha ?? null,
+            last_active_task: record.last_active_task ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Advance the marker, merging partial fields onto any existing record.
+ *
+ * Marker-advance semantics (LD-02):
+ *   - last_run_at is always settable (it measures engagement).
+ *   - last_main_sha is optional — the caller passes it only AFTER the digest
+ *     was computed (even when empty). When undefined, the existing sha is kept.
+ *   - last_active_task is optional — the welcome-back task id, kept otherwise.
+ *
+ * No-op (returns null) when the git email is absent — there is no key to write.
+ *
+ * @param {string} projectRoot
+ * @param {{ last_run_at?: string, last_main_sha?: string|null, last_active_task?: string|null }} fields
+ * @returns {object|null} the written record, or null when there is no identity key.
+ *
+ * @internal
+ */
+export function advanceLastSeen(projectRoot, fields = {}) {
+    const path = markerPath(projectRoot);
+    if (!path)
+        return null;
+    let existing = {};
+    if (existsSync(path)) {
+        try {
+            existing = JSON.parse(readFileSync(path, 'utf-8')) || {};
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const record = {
+        last_run_at: fields.last_run_at !== undefined ? fields.last_run_at : (existing.last_run_at ?? null),
+        last_main_sha: fields.last_main_sha !== undefined ? fields.last_main_sha : (existing.last_main_sha ?? null),
+        last_active_task: fields.last_active_task !== undefined
+            ? fields.last_active_task
+            : (existing.last_active_task ?? null),
+    };
+    mkdirSync(lastSeenDir(projectRoot), { recursive: true });
+    atomicWriteJson(path, record);
+    return record;
+}
+//# sourceMappingURL=last-seen.mjs.map

package/dist/cli/coordination/last-seen.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"last-seen.mjs","sourceRoot":"","sources":["../../../src/cli/coordination/last-seen.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAExD,SAAS,WAAW,CAAC,WAAW;IAC/B,OAAO,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,WAAW,CAAC,CAAA;AACrE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAK;IAClC,OAAO,MAAM,CAAC,KAAK,CAAC;SAClB,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;AAC1B,CAAC;AAED,SAAS,UAAU,CAAC,WAAW;IAC9B,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE;QACtB,IAAI,CAAC;YACJ,OAAO,cAAc,CAAC,WAAW,CAAC,CAAA;QACnC,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAA;QACZ,CAAC;IACF,CAAC,CAAC,EAAE,CAAA;IACJ,IAAI,CAAC,QAAQ,EAAE,KAAK;QAAE,OAAO,IAAI,CAAA;IACjC,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,GAAG,IAAI,OAAO,CAAC,CAAA;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,WAAW;IACvC,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAA;IACpC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3C,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;QACtD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QACtD,OAAO;YACN,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;YACvC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;YAC3C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,IAAI;SACjD,CAAA;IACF,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,EAAE;IACvD,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAA;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAEtB,IAAI,QAAQ,GAAG,EAAE,CAAA;IACjB,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC;YACJ,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;QACzD,CAAC;QAAC,MAAM,CAAC;YACR,QAAQ,GAAG,EAAE,CAAA;QACd,CAAC;IACF,CAAC;IAED,MAAM,MAAM,GAAG;QACd,WAAW,EACV,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,IAAI,IAAI,CAAC;QACvF,aAAa,EACZ,MAAM,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,IAAI,IAAI,CAAC;QAC7F,gBAAgB,EACf,MAAM,CAAC,gBAAgB,KAAK,SAAS;YACpC,CAAC,CAAC,MAAM,CAAC,gBAAgB;YACzB,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,IAAI,IAAI,CAAC;KACvC,CAAA;IAED,SAAS,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACxD,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC7B,OAAO,MAAM,CAAA;AACd,CAAC"}

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

@@ -58,6 +58,21 @@ export function createCoordinationStore(projectRoot: any): {
             data: any;
         };
     } | null;
+    /**
+     * @internal — LD-01: read the per-machine Last-Seen Marker. Returns
+     * null when the git email is absent or the marker has not been written.
+     */
+    readLastSeen(): {
+        last_run_at: string | null;
+        last_main_sha: string | null;
+        last_active_task: string | null;
+    } | null;
+    /**
+     * @internal — LD-02: advance the Last-Seen Marker. `last_run_at` is
+     * always settable; `last_main_sha` / `last_active_task` are optional
+     * partial fields merged onto the existing record.
+     */
+    advanceLastSeen(fields?: {}): object | null;
     /** @internal */
     getIdentity(): any;
 };

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

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

package/dist/cli/coordination/store.mjs

@@ -32,6 +32,7 @@ import { atomicWriteJson } from '../util/io.mjs';
 import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs';
 import { appendLifecycleEvent } from './event-log.mjs';
 import { validateConductorEvent } from './event-schema.mjs';
+import { advanceLastSeen as lastSeenAdvance, readLastSeen as lastSeenRead } from './last-seen.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
@@ -134,6 +135,21 @@ export function createCoordinationStore(projectRoot) {
                 return null;
             }
         },
+        /**
+         * @internal — LD-01: read the per-machine Last-Seen Marker. Returns
+         * null when the git email is absent or the marker has not been written.
+         */
+        readLastSeen() {
+            return lastSeenRead(projectRoot);
+        },
+        /**
+         * @internal — LD-02: advance the Last-Seen Marker. `last_run_at` is
+         * always settable; `last_main_sha` / `last_active_task` are optional
+         * partial fields merged onto the existing record.
+         */
+        advanceLastSeen(fields = {}) {
+            return lastSeenAdvance(projectRoot, fields);
+        },
         /** @internal */
         getIdentity() {
             return getAgentIdentity(projectRoot);

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

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

package/dist/cli/coverage-check/user-outcomes.d.mts

@@ -1,8 +1,9 @@
 /**
  * @typedef {Object} UserOutcome
  * @property {string} id                — synthesized positional ID (O1, O2, ...)
- * @property {('electron'|'web'|'cli'|'api'|'electron+web')} surface
+ * @property {('electron'|'web'|'cli'|'api'|'mobile'|'electron+web')} surface
  * @property {string} text              — outcome prose (sans the surface tag and requires suffix)
+ * @property {string[]} inferred        — v0.9.0 — indented child bullets under the parent outcome (raw prose, no further parsing). Defaults to [] when no children are present.
  * @property {number} [requires]        — the digit captured from `*(requires ON N)*`, when present and valid
  */
 /**
@@ -49,11 +50,15 @@ export type UserOutcome = {
      * — synthesized positional ID (O1, O2, ...)
      */
     id: string;
-    surface: ("electron" | "web" | "cli" | "api" | "electron+web");
+    surface: ("electron" | "web" | "cli" | "api" | "mobile" | "electron+web");
     /**
      * — outcome prose (sans the surface tag and requires suffix)
      */
     text: string;
+    /**
+     * — v0.9.0 — indented child bullets under the parent outcome (raw prose, no further parsing). Defaults to [] when no children are present.
+     */
+    inferred: string[];
     /**
      * — the digit captured from `*(requires ON N)*`, when present and valid
      */

package/dist/cli/coverage-check/user-outcomes.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"user-outcomes.d.mts","sourceRoot":"","sources":["../../../src/cli/coverage-check/user-outcomes.mjs"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,+CAHW,MAAM,GACJ,uBAAuB,CAwJnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,uBAAuB,oBACvB,MAAM,GACJ,CAAC,MAAM,GAAC,MAAM,GAAC,OAAO,CAAC,CAiBnC;;;;;QApNa,MAAM;aACN,CAAC,UAAU,GAAC,KAAK,GAAC,KAAK,GAAC,KAAK,GAAC,cAAc,CAAC;;;;UAC7C,MAAM;;;;;;;UAMN,yBAAyB;;;;gBACzB,MAAM;;;;cACN,MAAM;;;;YACN,MAAM;;;oBAKN,OAAO;eACP,CAAC,QAAQ,GAAC,OAAO,GAAC,iBAAiB,GAAC,UAAU,CAAC;;cAE/C,WAAW,EAAE"}
+{"version":3,"file":"user-outcomes.d.mts","sourceRoot":"","sources":["../../../src/cli/coverage-check/user-outcomes.mjs"],"names":[],"mappings":"AA4CA;;;;;;;GAOG;AAEH;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,+CAHW,MAAM,GACJ,uBAAuB,CA0LnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,uBAAuB,oBACvB,MAAM,GACJ,CAAC,MAAM,GAAC,MAAM,GAAC,OAAO,CAAC,CAiBnC;;;;;QAvPa,MAAM;aACN,CAAC,UAAU,GAAC,KAAK,GAAC,KAAK,GAAC,KAAK,GAAC,QAAQ,GAAC,cAAc,CAAC;;;;UACtD,MAAM;;;;cACN,MAAM,EAAE;;;;;;;UAMR,yBAAyB;;;;gBACzB,MAAM;;;;cACN,MAAM;;;;YACN,MAAM;;;oBAKN,OAAO;eACP,CAAC,QAAQ,GAAC,OAAO,GAAC,iBAAiB,GAAC,UAAU,CAAC;;cAE/C,WAAW,EAAE"}

package/dist/cli/coverage-check/user-outcomes.mjs

@@ -32,17 +32,18 @@
  * See packages/framework/skills/apt-plan/SKILL.md Section 5.B for the
  * authoring contract.
  */
-const VALID_SURFACES = new Set(['electron', 'web', 'cli', 'api', 'electron+web']);
+const VALID_SURFACES = new Set(['electron', 'web', 'cli', 'api', 'mobile', 'electron+web']);
 const HEADING_RE = /^(#{1,6})\s+(.*)$/;
 const USER_OUTCOMES_HEADING_RE = /^user\s+outcomes\s*$/i;
 const EPIC_RE = /^\*\*Epic:\*\*\s+(.+)$/;
 const EMPTY_WITH_NOTE_RE = /^_No user-observable changes — pure refactor\._\s*$/;
-const OUTCOME_RE = /^-\s+\*\*ON\*\*\s+\[(electron|web|cli|api|electron\+web)\]:\s+(.+?)(\s+\*\(requires\s+ON\s+(\d+)\)\*)?\s*$/;
+const OUTCOME_RE = /^-\s+\*\*ON\*\*\s+\[(electron|web|cli|api|mobile|electron\+web)\]:\s+(.+?)(\s+\*\(requires\s+ON\s+(\d+)\)\*)?\s*$/;
 /**
  * @typedef {Object} UserOutcome
  * @property {string} id                — synthesized positional ID (O1, O2, ...)
- * @property {('electron'|'web'|'cli'|'api'|'electron+web')} surface
+ * @property {('electron'|'web'|'cli'|'api'|'mobile'|'electron+web')} surface
  * @property {string} text              — outcome prose (sans the surface tag and requires suffix)
+ * @property {string[]} inferred        — v0.9.0 — indented child bullets under the parent outcome (raw prose, no further parsing). Defaults to [] when no children are present.
  * @property {number} [requires]        — the digit captured from `*(requires ON N)*`, when present and valid
  */
 /**
@@ -151,26 +152,58 @@ export function parseUserOutcomes(specContent) {
             result.epic = epic;
         return result;
     }
-    // Parse outcome rows in document order. Skip non-matching lines (e.g.
-    // stray prose between outcomes) — they don't count as outcomes.
+    // Parse outcome rows in document order. v0.9.0 — walk the raw body lines
+    // (not the trimmed `outcomeLines`) so we preserve indentation of child
+    // bullets. A `**ON**` parent row is followed by zero or more indented
+    // child bullets (lines starting with at least 2 spaces + `- `); those
+    // children attach to the parent as `inferred: string[]` (raw prose, no
+    // further parsing). The children block ends at the next `**ON**` row,
+    // a non-indented line, or a section terminator (blank line followed by
+    // another non-bullet non-blank line is fine; the next `**ON**` always
+    // resets ownership).
     /** @type {UserOutcome[]} */
     const outcomes = [];
     const rawRequires = [];
-    for (const line of outcomeLines) {
-        const m = line.match(OUTCOME_RE);
-        if (!m)
+    const CHILD_RE = /^(?: {2}|\t)+- (.+)$/;
+    let currentOutcomeIndex = -1;
+    for (let i = 0; i < bodyLines.length; i++) {
+        const rawLine = bodyLines[i];
+        const trimmed = rawLine.trim();
+        if (trimmed.length === 0) {
+            // Blank lines don't close the parent — children may resume after
+            // a blank line (loose-list markdown). The next non-blank line
+            // decides ownership.
             continue;
-        const surface = /** @type {UserOutcome['surface']} */ (m[1]);
-        if (!VALID_SURFACES.has(surface))
+        }
+        const onMatch = trimmed.match(OUTCOME_RE);
+        if (onMatch) {
+            const surface = /** @type {UserOutcome['surface']} */ (onMatch[1]);
+            if (!VALID_SURFACES.has(surface)) {
+                currentOutcomeIndex = -1;
+                continue;
+            }
+            const text = onMatch[2].trim();
+            const id = 'O' + (outcomes.length + 1);
+            const outcome = /** @type {UserOutcome} */ ({ id, surface, text, inferred: [] });
+            if (onMatch[4]) {
+                const n = Number.parseInt(onMatch[4], 10);
+                rawRequires.push({ outcomeIndex: outcomes.length, requires: n });
+            }
+            outcomes.push(outcome);
+            currentOutcomeIndex = outcomes.length - 1;
+            continue;
+        }
+        // Non-`**ON**` non-blank line. If it's an indented child bullet AND
+        // we have a current outcome, attach it. Otherwise (e.g. Epic line,
+        // sentinel, stray prose), drop ownership.
+        const childMatch = rawLine.match(CHILD_RE);
+        if (childMatch && currentOutcomeIndex >= 0) {
+            outcomes[currentOutcomeIndex].inferred.push(childMatch[1].trim());
             continue;
-        const text = m[2].trim();
-        const id = 'O' + (outcomes.length + 1);
-        const outcome = /** @type {UserOutcome} */ ({ id, surface, text });
-        if (m[4]) {
-            const n = Number.parseInt(m[4], 10);
-            rawRequires.push({ outcomeIndex: outcomes.length, requires: n });
         }
-        outcomes.push(outcome);
+        // Non-indented, non-`**ON**` line — closes the current outcome's
+        // child block. (The next `**ON**` will start a new block.)
+        currentOutcomeIndex = -1;
     }
     if (outcomes.length === 0) {
         // Header present, prose present, but no parseable `**ON**` rows —