@aperant/framework 0.10.0 → 0.11.0

package/src/cli/commands/pr-review.mjs

@@ -727,17 +727,30 @@ function parseGhPrView(raw) {
  * the viewer's personal handle (e.g. `AndyMik90`). They never match, which
  * previously caused every same-repo, owned PR to be mis-classified as
  * `external` and silently disabled auto-fix. The third arg `baseRepoOwner`
- * is the source of truth for "is this a fork PR?". `viewerLogin` is kept
- * only for backward-compatible signal reporting.
+ * is the source of truth for "is this a fork PR?".
+ *
+ * IMPORTANT (G44): "owned" means "a PR I authored," NOT "a branch in a repo I
+ * can push to." The owned test is strictly `gh.author.login === viewerLogin`
+ * — author IDENTITY, not `authorAssociation`. Previously a same-repo PR with
+ * `authorAssociation ∈ {OWNER, MEMBER, COLLABORATOR}` was classified `owned`,
+ * which meant every teammate's same-repo PR triggered the auto-fix-and-push
+ * pipeline on their branch. Now `authorAssociation` is retained only in the
+ * signal for human-readable tracing; it no longer gates the decision. The
+ * "is this mine" comparand is `gh.author?.login`, never `headRepoOwner`
+ * (comparing headRepoOwner to viewerLogin was the H1 bug — it never matches
+ * on an org-owned repo). Fork detection and author identity are independent:
+ * fork detection answers "did this come from a fork?"; author identity
+ * answers "did I write it?".
  *
  * @param {Record<string, any> | null | undefined} gh    parsed `gh pr view` JSON (may have `authorAssociation` grafted in by the REST-fetch path)
- * @param {string | null | undefined} viewerLogin        personal login from `gh api user` (fallback comparand for fork detection)
- * @param {string | null | undefined} [baseRepoOwner]    the org/user that owns the repo the PR targets (preferred comparand)
+ * @param {string | null | undefined} viewerLogin        personal login from `gh api user` (compared to `gh.author.login` for the owned test)
+ * @param {string | null | undefined} [baseRepoOwner]    the org/user that owns the repo the PR targets (fork-detection comparand)
  * @returns {{ authorship_mode: 'owned' | 'external' | 'unknown', authorship_signal: string }}
  */
 export function decideAuthorshipFromGh(gh, viewerLogin, baseRepoOwner = null) {
 	if (!gh) return { authorship_mode: 'unknown', authorship_signal: 'gh_payload_missing' }
 	const association = gh.authorAssociation ?? gh.author?.association ?? null
+	const author = gh.author?.login ?? null
 	const headRepoOwner =
 		gh.headRepository?.owner?.login ??
 		gh.headRepositoryOwner?.login ??
@@ -745,28 +758,36 @@ export function decideAuthorshipFromGh(gh, viewerLogin, baseRepoOwner = null) {
 		null
 	// Prefer baseRepoOwner when supplied; fall back to viewerLogin only for
 	// older callers that haven't been updated yet (e.g. legacy tests). The
-	// fallback preserves prior behavior for the personal-repo case.
+	// fallback preserves prior fork-detection behavior for the personal-repo
+	// case.
 	const compareOwner = baseRepoOwner ?? viewerLogin
 	const isFork = headRepoOwner && compareOwner && headRepoOwner !== compareOwner
 
-	const ownerLike = ['OWNER', 'MEMBER', 'COLLABORATOR']
 	const externalLike = ['NONE', 'CONTRIBUTOR', 'FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER']
 
-	if (!isFork && association && ownerLike.includes(association)) {
+	// G44: owned ⟺ (not a fork) AND the PR was authored by the running viewer.
+	if (!isFork && author && viewerLogin && author === viewerLogin) {
 		return {
 			authorship_mode: 'owned',
-			authorship_signal: `authorAssociation=${association}, same-repo branch (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'})`,
+			authorship_signal: `authored-by-viewer (author=${author}, viewer=${viewerLogin}), same-repo branch (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'}), authorAssociation=${association ?? 'null'}`,
 		}
 	}
-	if (isFork || (association && externalLike.includes(association))) {
+	// Forks, external-like associations, AND non-fork PRs authored by someone
+	// other than the viewer (a teammate's same-repo PR — the G44 case) all
+	// resolve to external (comment-only).
+	if (
+		isFork ||
+		(association && externalLike.includes(association)) ||
+		(!isFork && author && viewerLogin && author !== viewerLogin)
+	) {
 		return {
 			authorship_mode: 'external',
-			authorship_signal: `authorAssociation=${association}, fork=${Boolean(isFork)} (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'})`,
+			authorship_signal: `authorAssociation=${association ?? 'null'}, fork=${Boolean(isFork)}, author=${author ?? '?'}, viewer=${viewerLogin ?? '?'} (head=${headRepoOwner ?? '?'}, base=${compareOwner ?? '?'})`,
 		}
 	}
 	return {
 		authorship_mode: 'unknown',
-		authorship_signal: `authorAssociation=${association ?? 'null'}, fork=${Boolean(isFork)}`,
+		authorship_signal: `authorAssociation=${association ?? 'null'}, fork=${Boolean(isFork)}, author=${author ?? 'null'}`,
 	}
 }
 

package/src/cli/commands/route.mjs

@@ -32,7 +32,12 @@ import {
 	getTaskIsolationConfig,
 	getTrustedSkillSources,
 	loadMergedProjectConfig,
+	loadProjectConfig,
 } from '../config/load.mjs'
+import { resolveSharePolicy } from '../config/share-policy.mjs'
+import { computeCatchUpPanel } from '../coordination/catch-up.mjs'
+import { createCoordinationStore } from '../coordination/store.mjs'
+import { resolveLocalDefaultBranch } from '../git/default-branch.mjs'
 import '../gate/gates/index.mjs'
 import * as gateRegistry from '../gate/registry.mjs'
 import { detectHost, SUPPORTED_HOSTS } from '../host/detect.mjs'
@@ -96,6 +101,78 @@ function readUpdateCheckCache() {
 	return null
 }
 
+/**
+ * Is this an interactive (TTY) apt call? The catch-up panel + Last-Seen Marker
+ * are gated to interactive contexts (LD-02) — exactly like the statusline
+ * isTTY gate — so spawned subagents, fan-out workers, and non-TTY/piped calls
+ * are strict no-ops (they neither read nor write the marker). `APT_FORCE_TTY`
+ * forces the gate open for tests; `APT_CATCH_UP_DISABLE` forces it closed so a
+ * background spawner can opt every nested call out.
+ */
+function isInteractiveTty() {
+	if (process.env.APT_CATCH_UP_DISABLE === '1') return false
+	if (process.env.APT_FORCE_TTY === '1') return true
+	return Boolean(process.stdout?.isTTY || process.stderr?.isTTY)
+}
+
+/**
+ * Lazy-compute the catch-up panel for an interactive call and advance the
+ * Last-Seen Marker AFTER the panel is evaluated (R2/LD-02). Returns the panel
+ * (or null) to fold onto the route envelope as a top-level `catch_up` field.
+ *
+ * Marker-advance ordering (correctness-critical):
+ *   - last_run_at    = now              — always (engagement, not greeting);
+ *   - last_main_sha  = defaultBranch.sha — only AFTER the digest was computed,
+ *                                          i.e. only when we resolved a branch
+ *                                          (even when the digest is empty);
+ *   - last_active_task = welcome-back task id, when present.
+ *
+ * Non-TTY callers never reach this function (the caller gates on
+ * isInteractiveTty), so background/spawned calls never touch the marker.
+ *
+ * @param {string} targetDir
+ * @returns {object|null} the catch_up panel, or null.
+ */
+function computeCatchUpForRoute(targetDir) {
+	// Setup mirrors cmdCatchUp in commands/catch-up.mjs (recompute-only variant).
+	const config = loadProjectConfig(targetDir)
+	if (!config) return null
+
+	const store = createCoordinationStore(targetDir)
+	const marker = store.readLastSeen()
+	const td = config?.collaboration?.team_digest
+	const vis = resolveSharePolicy(config).visibility
+	const needsDigest = td?.enabled !== false && (vis === 'team' || vis === 'oss')
+	const defaultBranch = needsDigest ? resolveLocalDefaultBranch(targetDir) : null
+	const now = Date.now()
+
+	let panel = null
+	try {
+		panel = computeCatchUpPanel(targetDir, {
+			config,
+			now,
+			marker,
+			defaultBranch,
+		})
+	} catch (e) {
+		console.warn('[apt] catch-up:', e?.message ?? e)
+		panel = null
+	}
+
+	// Advance the marker AFTER panel eval. last_main_sha only when we actually
+	// resolved a default branch (the digest was computed, possibly empty).
+	const advance = { last_run_at: new Date(now).toISOString() }
+	if (defaultBranch?.sha) advance.last_main_sha = defaultBranch.sha
+	if (panel?.welcome_back?.task_id) advance.last_active_task = panel.welcome_back.task_id
+	try {
+		store.advanceLastSeen(advance)
+	} catch {
+		/* best-effort — never block routing on a marker write */
+	}
+
+	return panel
+}
+
 /**
  * Deterministic mapping from an explicit track flag (--quick/--deep/--debug)
  * to its canonical {track, primary_skill} pair. Flag overrides are user
@@ -309,6 +386,13 @@ export function cmdRoute(projectDir, extraArgs) {
 		}
 	}
 
+	// Catch-up panel (LD-11): lazy-compute on interactive (TTY) calls only, and
+	// only when config exists (init has no config yet). The compute also
+	// advances the Last-Seen Marker after panel eval (LD-02). Non-TTY calls are
+	// strict no-ops — no read, no write, no field. Folded onto every returned
+	// envelope below as a top-level `catch_up` field, mirroring update_check.
+	const catch_up = hasConfig && isInteractiveTty() ? computeCatchUpForRoute(targetDir) : null
+
 	// ---------------- Deterministic branches (zero-behavior-change) ----------------
 	// These fire regardless of host detection status — missing host is not
 	// fatal for init/status/help/skill-passthrough.
@@ -322,6 +406,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up: null,
 			reason: 'No .aperant/config.json found — first-time setup required',
 		})
 	}
@@ -335,6 +420,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			reason: 'No input provided — showing project status',
 		})
 	}
@@ -348,6 +434,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			reason: 'Help requested',
 		})
 	}
@@ -395,6 +482,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			...(gate_preview ? { gate_preview } : {}),
 			reason: `Direct skill invocation: apt:${firstWord}`,
 		})
@@ -444,6 +532,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			...(gate_preview ? { gate_preview } : {}),
 			...(spar_inject_gates ? { spar_inject_gates } : {}),
 			classification: {
@@ -523,7 +612,9 @@ export function cmdRoute(projectDir, extraArgs) {
 		)
 	}
 
-	return ok(envelope)
+	// Fold the catch-up panel onto the classify envelope as a top-level field,
+	// mirroring update_check (LD-11). null when non-TTY / neither half fires.
+	return ok({ ...envelope, catch_up })
 }
 
 /**

package/src/cli/config/share-policy.mjs

@@ -254,6 +254,7 @@ export function buildPolicyIgnoreMatcher(policy) {
 			rest.startsWith('events/') ||
 			rest.startsWith('locks/') ||
 			rest.startsWith('team-status/') ||
+			rest.startsWith('last-seen/') ||
 			rest.startsWith('paused/') ||
 			rest.startsWith('rationalizations/') ||
 			rest === 'digests/.last-run.json' ||

package/src/cli/config/upgrade-gitignore.mjs

@@ -189,6 +189,7 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 	// maintainer cannot accidentally un-ignore it with a broad `!config*.json`
 	// allow rule.
 	lines.push('config.local.json')
+	lines.push('last-seen/')
 	lines.push('')
 	lines.push('# ── Derived markdown indexes (regenerated from JSON) ──────────────')
 	lines.push('tasks/INDEX.md')

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

@@ -0,0 +1,231 @@
+/**
+ * @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 }
+}

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

@@ -0,0 +1,131 @@
+/**
+ * @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
+}

package/src/cli/coordination/store.mjs

@@ -33,6 +33,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,
@@ -152,6 +153,23 @@ export function createCoordinationStore(projectRoot) {
 			}
 		},
 
+		/**
+		 * @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/src/cli/dispatch.mjs

@@ -39,6 +39,7 @@ import { cmdAdr } from './commands/adr.mjs'
 import { cmdAudit } from './commands/audit.mjs'
 import { cmdAuthorSkill } from './commands/author-skill.mjs'
 import { cmdBootstrap } from './commands/bootstrap.mjs'
+import { cmdCatchUp } from './commands/catch-up.mjs'
 import { cmdCheck } from './commands/check.mjs'
 import { cmdCheckVersion } from './commands/check-version.mjs'
 import { cmdCiWatch, cmdCiWatchSweep } from './commands/ci-watch.mjs'
@@ -212,6 +213,7 @@ export const DISPATCH = {
 
 	// ---- (positional dir, slice(2)) shape ----
 	state: (args) => wrap(cmdState)(args[1]),
+	'catch-up': (args) => wrap(cmdCatchUp)(args[1]),
 	config: (args) => wrap(cmdConfig)(args[1], args.slice(2)),
 	'state-update': (args) => wrap(cmdStateUpdate)(args[1], args.slice(2)),
 	'state-artifacts': (args) => wrap(cmdStateArtifacts)(args[1], args.slice(2)),