Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat([issue-12769]): show which live runs block a claim-owner cleanup

[._.]/ Adam Eivy5f865c56a00d
diff --git a/client/src/components/cos/AgentResultLine.jsx b/client/src/components/cos/AgentResultLine.jsx
index 23c09341b3..fbff69f35a 100644
--- a/client/src/components/cos/AgentResultLine.jsx
+++ b/client/src/components/cos/AgentResultLine.jsx
@@ -1,3 +1,5 @@
+import { Fragment } from 'react';
+import { Link } from 'react-router';
import { CheckCircle, AlertCircle, RotateCcw } from 'lucide-react';
import { formatCount, formatUsd } from '../../utils/formatters';
import { isAgentHandoff, agentHandoffReason } from '../../lib/agentOutcome';
@@ -46,7 +48,7 @@ export default function AgentResultLine({ agent, className = '' }) {
)}
</span>
{interruption && <div>Execution interrupted: {interruption.category === 'content-refusal' ? 'provider safety refusal; automatic retry stopped' : interruption.category}</div>}
- {cleanupPending && <div>Cleanup {cleanup?.status === 'already-absent' ? 'already absent; preservation unverified' : cleanup?.status === 'blocked' ? 'blocked' : 'unverified/pending'}{cleanup?.reason ? `: ${cleanup.reason}` : ''}</div>}
+ {cleanupPending && <div>Cleanup {cleanup?.status === 'already-absent' ? 'already absent; preservation unverified' : cleanup?.status === 'blocked' ? 'blocked' : 'unverified/pending'}{cleanup?.reason ? `: ${cleanup.reason}` : ''}<CleanupHolders owners={cleanup?.owners} /></div>}
<SecurityScanEvidence scanner={scanner} control={agent.metadata?.securityScanControl} />
{!handoff && assessment && <div>{assessment.status === 'recorded' ? 'Assessment saved' : assessment.status === 'persistence-failed' ? 'Assessment could not be saved' : assessment.status === 'not-attempted' ? 'Assessment not attempted' : 'Assessment not verified as saved'}</div>}
{!handoff && validationFailed && <div>Delivery validation failed</div>}
@@ -55,6 +57,23 @@ export default function AgentResultLine({ agent, className = '' }) {
);
}
+// The live run(s) a claim-owner hold waits on. Without them the card said only
+// "claim-owner-ambiguous" and the operator had to hunt for the run (#12769).
+function CleanupHolders({ owners }) {
+ if (!Array.isArray(owners) || owners.length === 0) return null;
+ return (
+ <span className="break-words">
+ {' '}— waiting on {owners.length === 1 ? 'live run' : 'live runs'}{' '}
+ {owners.map((id, index) => (
+ <Fragment key={id}>
+ {index > 0 && ', '}
+ <Link to={`/cos/agents/${encodeURIComponent(id)}`} className="font-mono underline">{id}</Link>
+ </Fragment>
+ ))}
+ </span>
+ );
+}
+
export function SecurityScanEvidence({ scanner, control }) {
if (!scanner) return null;
return (
diff --git a/client/src/components/cos/AgentResultLine.test.jsx b/client/src/components/cos/AgentResultLine.test.jsx
index ee244c0bee..03c584fb7b 100644
--- a/client/src/components/cos/AgentResultLine.test.jsx
+++ b/client/src/components/cos/AgentResultLine.test.jsx
@@ -114,3 +114,13 @@ it('does not promote historical cleanup process success to verified cleanup', ()
view.rerender(<AgentResultLine agent={{ ...agent, metadata: { ...agent.metadata, cleanupOutcome: { status: 'verified' } } }} />);
expect(screen.getByText('Completed successfully')).toBeInTheDocument();
});
+
+it('names the live runs a claim-owner cleanup hold is waiting on', async () => {
+ const { MemoryRouter } = await import('react-router');
+ const cleanupOutcome = { status: 'blocked', reason: 'claim-owner-ambiguous', owners: ['agent-aaa', 'agent-bbb'] };
+ render(<MemoryRouter><AgentResultLine agent={{ result: { success: true }, metadata: { cleanupOutcome } }} /></MemoryRouter>);
+ const first = screen.getByRole('link', { name: 'agent-aaa' });
+ expect(first.closest('div')).toHaveTextContent('Cleanup blocked: claim-owner-ambiguous — waiting on live runs agent-aaa, agent-bbb');
+ expect(first).toHaveAttribute('href', '/cos/agents/agent-aaa');
+ expect(screen.getByRole('link', { name: 'agent-bbb' })).toHaveAttribute('href', '/cos/agents/agent-bbb');
+});
diff --git a/server/lib/README.md b/server/lib/README.md
index 4d3d755346..1b05a19f8f 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -554,7 +554,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `taskRetryHold.js` | The failed-task RETRY HOLD state (#3373) — pure metadata helpers shared by the failure verdict, the post-cleanup release, the spawn guard, and the orphan sweep. `retryHoldMetadata(agentId, now)` arms it (task stays `in_progress`, so no dequeue tier can claim the retry before its resume pointer is resolved); `clearedRetryHoldMetadata()` releases it in the same write that flips the task to `pending`; `isRetryHeld(metadata)` / `isRetryHoldOwner(metadata, agentId)` gate the spawn and the owner-scoped release; `isStaleRetryHold(metadata, now, graceMs)` + `RETRY_HOLD_GRACE_MS` let the orphan sweep finish a transition whose process died. |
| `taskStatusTransition.js` | The CoS task STATUS TRANSITION vocabulary (#6620) — `resolveTaskStatusTransition(previousStatus, nextStatus)` classifies one update's status pair ONCE and returns `{ action, isRevive, isRequeue, entersInProgress, leavesInProgress, leavesBlocked, isTerminal }`, so `writeTaskUpdate`'s blocked/pause clear, resume-pointer drop, retry-hold retire, claim release, requeue stamp and emitted `tasks:changed` action all read one answer instead of re-deriving seven. A falsy `nextStatus` means "this patch carries no status" (a lease-renewal heartbeat) and releases nothing. `isTerminalTaskStatus(status)` is the shared `completed`/`blocked` predicate `cosTaskStore` and `cosTaskMerge` both read. Pure — metadata predicates (is this block a pause?) stay at the application site. |
| `taskTargetBranch.js` | Pure task-branch contract: `resolveTaskTargetBranch(metadata)` reads a retry's legacy `existingBranch` or a review-loop follow-up's canonical `reviewLoopPRBranch`; `shouldStripTaskTargetBranch(metadata)` identifies only retry-owned pointers for terminal cleanup. |
-| `claimContinuation.js` | Claim-flow relaunch pointer. `claimContinuationBranch(claimTarget)` is the `claim/issue-<n>` or `claim/<key>` branch a pinned target checks out. `claimContinuationPointer(...)` names the `claim-*` worktree already holding that branch when a relaunch should finish it in place (locked, prunable, unmanaged, or occupied by another running/paused agent → null). `claimContinuationWorkspace(...)` turns a still-on-disk pointer into the cwd the next agent uses without moving the directory. `claimOwnershipBinding(task)` is the branch (or "picks its own", for a swarm orchestrator; a pinned run is also "still choosing" until it binds) a claim run registers on its agent record; `bindClaimBranch` / `releaseClaimBranch` patch the concrete branches a run binds before cutting them (an epic's child, a picked issue), `ownsClaimBranch(agent, branch)` is explicit registered/bound ownership only (never a picker's "may pick"), `claimCheckoutOwnerReason(...)` names a live/possible claim owner for branch-reconcile, and `claimBranchAdmission(...)` gates coordinator adoption and detach with the same branch/repository owners; `claimContinuationAdmission(...)` is the launch-time ownership check that re-reads holder, branch and live owners before a cached pointer may be entered (anything unreadable or changed → refuse, the caller defers; a possible swarm owner holds the launch until that run ends). |
+| `claimContinuation.js` | Claim-flow relaunch pointer. `claimContinuationBranch(claimTarget)` is the `claim/issue-<n>` or `claim/<key>` branch a pinned target checks out. `claimContinuationPointer(...)` names the `claim-*` worktree already holding that branch when a relaunch should finish it in place (locked, prunable, unmanaged, or occupied by another running/paused agent → null). `claimContinuationWorkspace(...)` turns a still-on-disk pointer into the cwd the next agent uses without moving the directory. `claimOwnershipBinding(task)` is the branch (or "picks its own", for a swarm orchestrator; a pinned run is also "still choosing" until it binds) a claim run registers on its agent record; `bindClaimBranch` / `releaseClaimBranch` patch the concrete branches a run binds before cutting them (an epic's child, a picked issue), `ownsClaimBranch(agent, branch)` is explicit registered/bound ownership only (never a picker's "may pick"), `claimCheckoutOwnerReason(...)` names a live/possible claim owner for branch-reconcile (`claimCheckoutOwner(...)` adds the holder run ids a blocked cleanup records), and `claimBranchAdmission(...)` gates coordinator adoption and detach with the same branch/repository owners; `claimContinuationAdmission(...)` is the launch-time ownership check that re-reads holder, branch and live owners before a cached pointer may be entered (anything unreadable or changed → refuse, the caller defers; a possible swarm owner holds the launch until that run ends). |
| `scheduledTaskTypes.js` | Registered scheduled task names (`SELF_IMPROVEMENT_TASK_TYPES`), shared by schedule configuration and authoritative skill routing; plus the retired-name map (`TASK_TYPE_RENAMES`, `currentTaskTypeName`, `taskExecutionKey`) for tasks and records written before a task rename. |
| `scheduleExecutionFieldsValidation.js` | `scheduleExecutionFieldsSchema` validates optional prompt and provider/model selections before schedule writes, preserving null/empty clears. |
| `scheduleRunOrder.js` | Storage rules for a task's advisory `suggestedAfter` list — which OTHER scheduled tasks to run first. `normalizeSuggestedAfter` drops blanks, duplicates and self-references and caps at `SUGGESTED_AFTER_MAX`; the shipped order it defaults to is `auditCatalog.AUDIT_SUGGESTED_AFTER`, layered at read time in `getScheduleStatus`. Advisory only — the ENFORCED dependency field is `runAfter`. Pure — no I/O. |
diff --git a/server/lib/claimContinuation.js b/server/lib/claimContinuation.js
index cd625b2a21..c0f7af5c98 100644
--- a/server/lib/claimContinuation.js
+++ b/server/lib/claimContinuation.js
@@ -236,22 +236,30 @@ function mayPickClaimBranch(agent, branchName) {
* that has not yet bound the branch it works on, in this same repository,
* so it might be the one that cut this tree — unprovable from the registry
* alone.
- * `active` outranks `ambiguous` across the whole list.
+ * `active` outranks `ambiguous` across the whole list. `holderIds` names the
+ * run(s) behind the verdict — the one active owner, or every possible one — so
+ * a blocked cleanup can say which live run it is waiting on.
*
- * @returns {'active'|'ambiguous'|null}
+ * @returns {{ occupancy: 'active'|'ambiguous'|null, holderIds: string[] }}
*/
-function claimHolderOccupancy({ agents, holderPath, branchName, sourceWorkspace, ignoreIds }) {
- let ambiguous = false;
+function scanClaimHolders({ agents, holderPath, branchName, sourceWorkspace, ignoreIds }) {
+ const possible = [];
const claimHolder = /^(claim|next)\//.test(branchName) || isHumanClaimWorktree(worktreeAgentId(holderPath));
for (const agent of agents) {
if (!agent || ignoreIds.has(agent.id) || !isLiveAgent(agent)) continue;
const workspace = agentWorkspace(agent);
- if (samePath(workspace, holderPath) || (holderPath && workspace && isPathInsideDir(holderPath, workspace))) return 'active';
+ if (samePath(workspace, holderPath) || (holderPath && workspace && isPathInsideDir(holderPath, workspace))) {
+ return { occupancy: 'active', holderIds: [agent.id].filter(Boolean) };
+ }
if (!inRepository(agent, sourceWorkspace)) continue;
- if (ownsClaimBranch(agent, branchName)) return 'active';
- if (claimHolder && mayPickClaimBranch(agent, branchName)) ambiguous = true;
+ if (ownsClaimBranch(agent, branchName)) return { occupancy: 'active', holderIds: [agent.id].filter(Boolean) };
+ if (claimHolder && mayPickClaimBranch(agent, branchName)) possible.push(agent.id);
}
- return ambiguous ? 'ambiguous' : null;
+ return possible.length ? { occupancy: 'ambiguous', holderIds: possible.filter(Boolean) } : { occupancy: null, holderIds: [] };
+}
+
+function claimHolderOccupancy(input) {
+ return scanClaimHolders(input).occupancy;
}
/**
@@ -400,11 +408,23 @@ export function claimContinuationAdmission({ metadata, agentId, sourceWorkspace,
* @param {{ branchName: string, holderPath?: string|null, sourceWorkspace?: string, agents: Array<object>|null, ignoreIds?: string[] }} input
* @returns {'claim-owner-active'|'claim-owner-ambiguous'|'claim-ownership-unreadable'|null}
*/
-export function claimCheckoutOwnerReason({ branchName, holderPath = null, sourceWorkspace, agents, ignoreIds = [] }) {
+export function claimCheckoutOwnerReason(input) {
+ return claimCheckoutOwner(input)?.reason ?? null;
+}
+
+/**
+ * `claimCheckoutOwnerReason` plus the live run ids behind it, for a caller that
+ * records the hold where a person reads it (the Agent card's cleanup line).
+ * `owners` is empty for an unreadable registry.
+ *
+ * @param {{ branchName: string, holderPath?: string|null, sourceWorkspace?: string, agents: Array<object>|null, ignoreIds?: string[] }} input
+ * @returns {{ reason: 'claim-owner-active'|'claim-owner-ambiguous'|'claim-ownership-unreadable', owners: string[] }|null}
+ */
+export function claimCheckoutOwner({ branchName, holderPath = null, sourceWorkspace, agents, ignoreIds = [] }) {
if (!Array.isArray(agents) || !branchName
- || agents.some(agent => !agent || !['running', 'paused', 'completed'].includes(agent.status))) return 'claim-ownership-unreadable';
- const occupancy = claimHolderOccupancy({
+ || agents.some(agent => !agent || !['running', 'paused', 'completed'].includes(agent.status))) return { reason: 'claim-ownership-unreadable', owners: [] };
+ const { occupancy, holderIds } = scanClaimHolders({
agents, holderPath, branchName, sourceWorkspace, ignoreIds: new Set(ignoreIds.filter(Boolean)),
});
- return occupancy ? `claim-owner-${occupancy}` : null;
+ return occupancy ? { reason: `claim-owner-${occupancy}`, owners: holderIds } : null;
}
diff --git a/server/services/agentRepoStateVerification.js b/server/services/agentRepoStateVerification.js
index 1d9d3f4bc0..579c812508 100644
--- a/server/services/agentRepoStateVerification.js
+++ b/server/services/agentRepoStateVerification.js
@@ -319,13 +319,13 @@ async function verifyRunBranches(input) {
const results = [];
for (const branch of branches) {
const { readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');
- const { claimCheckoutOwnerReason } = await import('../lib/claimContinuation.js');
+ const { claimCheckoutOwner } = await import('../lib/claimContinuation.js');
const agents = await readClaimOwnershipAgents().catch(() => null);
- const owner = claimCheckoutOwnerReason({ branchName: branch, sourceWorkspace, agents });
+ const owner = claimCheckoutOwner({ branchName: branch, sourceWorkspace, agents });
if (owner) {
const { recordCleanupOutcome } = await import('./cosAgentLifecycle.js');
- await recordCleanupOutcome(input.agentId, { branch, status: 'blocked', reason: owner });
- results.push({ branch, verified: false, skipReason: owner, issues: [], recoveryTaskId: null });
+ await recordCleanupOutcome(input.agentId, { branch, status: 'blocked', reason: owner.reason, owners: owner.owners });
+ results.push({ branch, verified: false, skipReason: owner.reason, issues: [], recoveryTaskId: null });
continue;
}
// A current branch holder is not evidence of the old claim's checkout.
@@ -420,10 +420,10 @@ async function verifyAgentBranchState({ agentId, task, agentState, success, prEx
}
}
const { readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');
- const { claimCheckoutOwnerReason } = await import('../lib/claimContinuation.js');
- const owner = claimCheckoutOwnerReason({ branchName, sourceWorkspace,
+ const { claimCheckoutOwner } = await import('../lib/claimContinuation.js');
+ const owner = claimCheckoutOwner({ branchName, sourceWorkspace,
agents: await readClaimOwnershipAgents().catch(() => null) });
- if (owner) { await domain('blocked', owner); return skipped(owner); }
+ if (owner) { await domain('blocked', owner.reason, { owners: owner.owners }); return skipped(owner.reason); }
const observed = await probeRepoState({
sourceWorkspace,
branchName,
diff --git a/server/services/agentRepoStateVerification.test.js b/server/services/agentRepoStateVerification.test.js
index 53fba90bca..3b5af12281 100644
--- a/server/services/agentRepoStateVerification.test.js
+++ b/server/services/agentRepoStateVerification.test.js
@@ -615,6 +615,19 @@ describe('claim-swarm completion', () => {
for (const branch of branches) expect(recordCleanupOutcome).toHaveBeenCalledWith('agent-1', expect.objectContaining({ branch, status: 'blocked' }));
expect(cleanupMerged).not.toHaveBeenCalled();
});
+ // #12769: "Cleanup blocked: claim-owner-ambiguous" named no run, so nobody
+ // could tell which live run to look at.
+ it('names the live runs that keep a swarm checkout ambiguous', async () => {
+ const pending = (id) => ({ id, status: 'running', workspacePath: '/repo',
+ metadata: { sourceWorkspace: '/repo', claimBranch: `claim/issue-${id.length}`, claimPicksOwnBranch: false, claimSelectionPending: true } });
+ readClaimOwnershipAgents.mockResolvedValue([pending('agent-a'), pending('agent-bb'),
+ { id: 'agent-done', status: 'completed', metadata: { sourceWorkspace: '/repo', claimSelectionPending: true } }]);
+ const state = agentState({ isWorktree: false, worktreeBranch: null, workspacePath: '/repo', claimPicksOwnBranch: true,
+ claimBranches: ['claim/issue-11'] });
+ await run({ agentState: state });
+ expect(recordCleanupOutcome).toHaveBeenCalledWith('agent-1', expect.objectContaining({
+ branch: 'claim/issue-11', status: 'blocked', reason: 'claim-owner-ambiguous', owners: ['agent-a', 'agent-bb'] }));
+ });
it('does not infer branches from output or override manual handoffs and failed retries', async () => {
const state = agentState({ isWorktree: false, worktreeBranch: null, claimPicksOwnBranch: true, claimBranches: ['claim/issue-11'] });
findPullRequestForBranch.mockResolvedValue({ status: 'found', detail: 'OPEN', url: 'https://github.com/example/repo/pull/11' });