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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Claim-flow relaunch — continue the worktree the previous run of this task
* already created, instead of treating that claim as someone else's.
*
* A claim agent cuts `claim/issue-<n>` (or `claim/<key>`) itself, under
* `data/cos/worktrees/claim-*`, and stamps `in-progress`. PortOS does not own
* that directory as an `agent-*` worktree, so a provider relaunch used to
* requeue onto a clean checkout. The replacement then followed the claim
* prompt's "already in progress / already on this branch → exit" rule and
* abandoned the work the user asked it to finish.
*
* The pointer stays on the claim directory. Moving it to `agent-<id>` would
* break the claim prompt's own path and the claim-shaped reaper. Pure: the
* git listing and the agent list stay with the caller.
*/
import { isAbsolute, resolve } from 'path';
import { isPlainObject } from './objects.js';
import { prStaysOpen } from './prDisposition.js';
import { isPathInsideDir } from './pathSafety.js';
import { isHumanClaimWorktree, worktreeAgentId } from './worktreeOwnership.js';
import { hasClaimFlowContract } from './claimFlowTaskTypes.js';
import { isTruthyMeta } from './metadataFlags.js';
const CASE_FOLD = process.platform === 'win32';
/** Branch a pinned claim target checks out, or null when the ref is not a claim name. */
export function claimContinuationBranch(claimTarget) {
const ref = String(claimTarget ?? '').trim();
if (!ref || ref.length > 80) return null;
if (/^\d+$/.test(ref)) return `claim/issue-${ref}`;
if (/^[A-Za-z][A-Za-z0-9]*-\d+$/.test(ref)) return `claim/${ref}`;
if (/^[a-z0-9][a-z0-9-]*$/i.test(ref)) return `claim/${ref}`;
return null;
}
function samePath(a, b) {
if (typeof a !== 'string' || typeof b !== 'string' || !a || !b) return false;
const left = resolve(a);
const right = resolve(b);
return CASE_FOLD ? left.toLowerCase() === right.toLowerCase() : left === right;
}
/**
* The claim ownership a claim-flow run registers on its agent record. PortOS does
* not provision the `claim-*` directory the agent cuts, so `workspacePath` never
* names it; the branch is the only identity both sides know:
* - a run pinned to a target owns exactly `claim/…` for that target;
* - an unpinned run (the issue picker, including a swarm orchestrator whose
* fan-out children cut their own trees) owns a branch it chooses later, so
* it is registered as possibly owning ANY claim branch in its repository
* until it binds the concrete ones (`bindClaimBranch`).
* Null for a task that is not a claim flow. Pure.
*
* @returns {{ claimBranch: string|null, claimPicksOwnBranch: boolean, claimSelectionPending?: true }|null}
*/
export function claimOwnershipBinding(task) {
if (!hasClaimFlowContract(task)) return null;
const claimBranch = claimContinuationBranch(task?.metadata?.claimTarget);
// A pinned run may still check out a DIFFERENT branch: a pinned tracking epic
// ships its first eligible child, and an oversized issue is split and its
// first slice shipped. Until the run binds the branch it actually works on
// (`bindClaimBranch`), it may own any claim tree in its repository.
return { claimBranch, claimPicksOwnBranch: !claimBranch, ...(claimBranch ? { claimSelectionPending: true } : {}) };
}
/** A branch a claim run may bind to itself: `claim/…` or slashdo's `next/…`. */
function isClaimOwnershipBranch(name) {
const branch = String(name ?? '');
return branch.length <= 200 && /^(claim|next)\/[A-Za-z0-9._/-]+$/.test(branch)
&& !branch.includes('..') && !branch.endsWith('/') && !branch.endsWith('.lock');
}
const ownershipList = (agent, key) => {
const list = agent?.metadata?.[key] ?? agent?.[key];
return Array.isArray(list) ? list.filter((b) => typeof b === 'string') : [];
};
/** Most branches one run may hold bound at once — a swarm binds one per child. */
export const MAX_BOUND_CLAIM_BRANCHES = 50;
/**
* The metadata patch that binds `branch` to a running claim run: the concrete
* branch it is about to check out (the pinned target, an epic's child, a split
* slice, or the issue a picker selected). The first binding settles the run's
* open selection (see `mayPickClaimBranch`). `{ refused }` when the record is
* not a live claim run, the branch is not claim-shaped, another live run in
* `agents` already owns it, or the bound list is full. Pure.
*
* @returns {{ claimBranches: string[], claimReleasedBranches: string[], claimSelectionPending: false }|{ refused: string }}
*/
export function bindClaimBranch(agent, branch, agents = []) {
const refused = bindingRefusal(agent, branch);
if (refused) return { refused };
// Another live run in this repository already owns the branch: binding it too
// would hand both runs the same checkout. A predecessor this run continues is
// not a rival. A merely POSSIBLE owner (a picker that has not bound) does not
// refuse — git refuses a second checkout of one branch on its own.
const occupancy = claimHolderOccupancy({
agents, holderPath: null, branchName: branch, sourceWorkspace: agentRepository(agent),
ignoreIds: new Set([agent.id, agent.metadata?.resumedFromAgentId].filter(Boolean)),
});
if (occupancy === 'active') return { refused: 'owner-active' };
const bound = ownershipList(agent, 'claimBranches');
if (!bound.includes(branch) && bound.length >= MAX_BOUND_CLAIM_BRANCHES) return { refused: 'too-many-branches' };
return {
claimBranches: bound.includes(branch) ? bound : [...bound, branch],
claimReleasedBranches: ownershipList(agent, 'claimReleasedBranches').filter((b) => b !== branch),
claimSelectionPending: false,
};
}
/**
* The metadata patch that explicitly releases `branch` from a running claim run
* that is handing it to somebody else before the run ends. Completion of the run
* releases everything without this. `{ refused }` on the same conditions as
* `bindClaimBranch`. Pure.
*/
export function releaseClaimBranch(agent, branch) {
const refused = releaseRefusal(agent, branch);
if (refused) return { refused };
const released = ownershipList(agent, 'claimReleasedBranches');
return {
claimBranches: ownershipList(agent, 'claimBranches').filter((b) => b !== branch),
...(Array.isArray(agent.metadata?.reconcileReservations)
? { reconcileReservations: agent.metadata.reconcileReservations.filter(target => target.branch !== branch) } : {}),
...(agent.metadata?.reconcileMergeReservation?.branch === branch ? { reconcileMergeReservation: null } : {}),
claimReleasedBranches: released.includes(branch) ? released : [...released, branch].slice(-MAX_BOUND_CLAIM_BRANCHES),
};
}
/**
* The metadata patch that reserves `branch` for a live branch-reconcile
* coordinator whose worker was just admitted to mutate it (#10096). It lands in
* the same `claimBranches` list a claim run's bindings use, so
* `claimHolderOccupancy` reports the coordinator as an `active` owner to `bind`,
* continuation and adoption until its run ends. Null when `branch` is not a
* claim-shaped name — no claim run can bind it, so there is nothing to reserve.
* `{ refused }` when the record is not a live run or its bound list is full. Pure.
*
* @returns {{ claimBranches: string[], claimReleasedBranches: string[] }|{ refused: string }|null}
*/
export function reserveReconcileBranch(agent, branch) {
if (!isClaimOwnershipBranch(branch)) return null;
if (!isLiveAgent(agent)) return { refused: 'owner-not-running' };
const held = ownershipList(agent, 'claimBranches');
if (!held.includes(branch) && held.length >= MAX_BOUND_CLAIM_BRANCHES) return { refused: 'too-many-branches' };
return {
claimBranches: held.includes(branch) ? held : [...held, branch],
claimReleasedBranches: ownershipList(agent, 'claimReleasedBranches').filter((b) => b !== branch),
};
}
/** Scheduler-derived reconciliation assignment; never inferred from prompt text.
* Kept as structured task metadata across persistence and snapshotted at launch.
* A reservation selects one exact target; the assignment itself grants no lease.
*/
export function reconcileAssignmentForTask(task) {
const meta = task?.metadata;
const assignment = meta?.reconcileAssignment;
if (task?.taskType !== 'internal' || meta?.analysisType !== 'branch-reconcile'
|| !isPlainObject(assignment) || assignment.appId !== meta.app
|| typeof assignment.appId !== 'string' || !assignment.appId
|| typeof assignment.repoPath !== 'string' || !isAbsolute(assignment.repoPath) || !isPlainObject(assignment.origin)
|| typeof assignment.origin.host !== 'string' || !assignment.origin.host
|| typeof assignment.origin.fullName !== 'string' || !assignment.origin.fullName
|| !Array.isArray(assignment.targets) || !assignment.targets.length
|| assignment.targets.some(target => !isPlainObject(target)
|| typeof target.branch !== 'string' || !target.branch
|| (target.workspacePath !== null && (typeof target.workspacePath !== 'string' || !isAbsolute(target.workspacePath)))
|| typeof target.merge !== 'boolean')) return null;
return structuredClone(assignment);
}
/** Match an exact target against both the registered and live assignment. */
export function reconcileAssignedTarget(agent, task, target, { bindCheckout = false } = {}) {
const assignment = reconcileAssignmentForTask(task);
const meta = agent?.metadata;
if (!assignment || agent.status !== 'running' || agent.taskId !== task.id
|| ['completed', 'failed', 'cancelled'].includes(task.status)
|| JSON.stringify(assignment) !== JSON.stringify(meta?.reconcileAssignment)
|| !samePath(meta.sourceWorkspace || meta.workspacePath, assignment.repoPath)
|| !isPlainObject(target)) return null;
const assigned = assignment.targets.find(row => row.branch === target.branch);
const reservations = meta.reconcileReservations ?? [];
if (!assigned || !Array.isArray(reservations) || reservations.some(row => !isPlainObject(row)
|| typeof row.branch !== 'string' || (row.workspacePath !== null
&& (typeof row.workspacePath !== 'string' || !isAbsolute(row.workspacePath))))) return null;
const reserved = reservations.find(row => row?.branch === target.branch);
const expectedPath = assigned.workspacePath ?? reserved?.workspacePath ?? null;
const observedPath = target.workspacePath ?? null;
// A scan may assign an existing branch before it has a checkout. Only the
// ownership service may bind its first observed holder; subsequent checks
// must preserve that holder even though the original assignment was null.
const matches = expectedPath ? samePath(expectedPath, observedPath)
: observedPath === null || (bindCheckout && typeof observedPath === 'string' && isAbsolute(observedPath));
if (!matches || (!bindCheckout && (!reserved || !samePath(reserved.workspacePath, observedPath)))) return null;
return { assignment, target: { ...assigned, workspacePath: observedPath } };
}
/** Assignment scope is not merge permission: retirement/review/handoff stay held. */
export function reconcileMergeTarget(agent, task, target) {
const proof = reconcileAssignedTarget(agent, task, target);
return proof?.target.merge && proof.target.workspacePath && !agent.metadata.configReadOnly && !isTruthyMeta(task.metadata.readOnly)
&& agent.metadata.prCompletionPolicy !== 'leave-open' && !prStaysOpen(task) && !isTruthyMeta(task.metadata.reviewLoopLeaveOpen)
&& ![false, 'false'].includes(task.metadata.autoMerge) ? proof : null;
}
/** Where the coordinator prompt's recheck command carries the run's own agent id. */
export const RECONCILE_AGENT_ID_PLACEHOLDER = '{agentId}';
const RECONCILE_AGENT_ID_FIELD = `,"agentId":"${RECONCILE_AGENT_ID_PLACEHOLDER}"`;
/**
* Fill a coordinator prompt's `{agentId}` slot at spawn time, once the run has an
* id (the in-flight block is generated before spawn). Without a usable id the
* field is dropped, so the recheck stays the read-only answer instead of sending
* a literal placeholder. Pure.
*/
export function injectReconcileAgentId(text, agentId) {
if (typeof text !== 'string' || !text.includes(RECONCILE_AGENT_ID_PLACEHOLDER)) return text;
const usable = typeof agentId === 'string' && /^[A-Za-z0-9_-]{1,200}$/.test(agentId);
return usable
? text.replaceAll(RECONCILE_AGENT_ID_PLACEHOLDER, agentId)
: text.replaceAll(RECONCILE_AGENT_ID_FIELD, '');
}
// A release may also come from a run that holds the branch by reservation rather
// than as a claim run (a branch-reconcile coordinator).
function releaseRefusal(agent, branch) {
if (isLiveAgent(agent) && Array.isArray(agent.metadata?.reconcileReservations)
&& agent.metadata.reconcileReservations.some(target => target.branch === branch)) return null;
if (isLiveAgent(agent) && ownershipList(agent, 'claimBranches').includes(branch)) {
return isClaimOwnershipBranch(branch) ? null : 'branch-invalid';
}
return bindingRefusal(agent, branch);
}
// Only a live claim run may change its own bindings, and only for a claim branch.
function bindingRefusal(agent, branch) {
if (!isLiveAgent(agent)) return 'owner-not-running';
const claimRun = Boolean(registeredClaimBranch(agent)) || isTruthyMeta(agent?.claimPicksOwnBranch ?? agent?.metadata?.claimPicksOwnBranch);
if (!claimRun) return 'claim-owner-unverified';
return isClaimOwnershipBranch(branch) ? null : 'branch-invalid';
}
function isLiveAgent(agent) {
return agent?.status === 'running' || agent?.status === 'paused';
}
function agentWorkspace(agent) {
return agent.workspacePath || agent.metadata?.workspacePath;
}
function agentRepository(agent) {
return agent.sourceWorkspace || agent.metadata?.sourceWorkspace || agentWorkspace(agent);
}
// Conservative: an agent whose repository cannot be read is treated as being in
// this one, because the alternative is to wave a possible owner through.
function inRepository(agent, sourceWorkspace) {
const repository = agentRepository(agent);
return !repository || !sourceWorkspace || samePath(repository, sourceWorkspace);
}
function registeredClaimBranch(agent) {
return agent?.claimBranch ?? agent?.metadata?.claimBranch;
}
// Every branch the run registered — its pinned target plus each branch it bound
// — minus the ones it explicitly released. A picker's "may pick" fallback is
// not ownership: callers that grant authority over a branch use this alone.
export function ownsClaimBranch(agent, branchName) {
if (ownershipList(agent, 'claimReleasedBranches').includes(branchName)) return false;
return registeredClaimBranch(agent) === branchName || ownershipList(agent, 'claimBranches').includes(branchName);
}
// A run that may hold a claim checkout nobody can name yet: a picker until it
// binds its first branch, a pinned run until it binds the branch it actually
// works on. The claim prompt binds every branch BEFORE its worktree exists, so
// once a run has bound one, each tree it cuts is named — releasing it later
// does not reopen the selection. A run that never binds (an older prompt, a
// provider that cannot curl) stays possible owner of every claim tree in its
// repository until it ends, except a branch it explicitly released.
function mayPickClaimBranch(agent, branchName) {
if (ownershipList(agent, 'claimReleasedBranches').includes(branchName)) return false;
if (isTruthyMeta(agent?.claimSelectionPending ?? agent?.metadata?.claimSelectionPending)) return true;
return isTruthyMeta(agent?.claimPicksOwnBranch ?? agent?.metadata?.claimPicksOwnBranch)
&& ownershipList(agent, 'claimBranches').length === 0
&& ownershipList(agent, 'claimReleasedBranches').length === 0;
}
/**
* Whether a running or paused agent other than `ignoreIds` holds, or may hold,
* the claim checkout:
* - `active`: it works inside the directory, or registered or bound this
* exact branch in this repository (and has not released it);
* - `ambiguous`: it is a claim run that picks its own branch, or a pinned run
* 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. `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 {{ occupancy: 'active'|'ambiguous'|null, holderIds: string[] }}
*/
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 { occupancy: 'active', holderIds: [agent.id].filter(Boolean) };
}
if (!inRepository(agent, sourceWorkspace)) continue;
const reservations = agent.metadata?.reconcileReservations;
if (reservations != null && (!Array.isArray(reservations) || reservations.some(target => !target || typeof target.branch !== 'string'))) { possible.push(agent.id); continue; }
if (reservations?.some(target => target?.branch === branchName) || ownsClaimBranch(agent, branchName)) return { occupancy: 'active', holderIds: [agent.id].filter(Boolean) };
if (claimHolder && mayPickClaimBranch(agent, branchName)) possible.push(agent.id);
}
return possible.length ? { occupancy: 'ambiguous', holderIds: possible.filter(Boolean) } : { occupancy: null, holderIds: [] };
}
function claimHolderOccupancy(input) {
return scanClaimHolders(input).occupancy;
}
/**
* The claim worktree this task's previous run left on its own branch, when
* PortOS may hand it to the relaunch. Null when there is nothing to continue:
* not a claim task, no pinned target, no holder, a lock, a tree outside the
* claim root, or another live or paused agent already working in that directory.
*
* @param {{
* task: object,
* agentId: string,
* worktrees?: Array<{path?: string, branch?: string, locked?: boolean, prunable?: boolean}>,
* agents?: Array<{id?: string, status?: string, workspacePath?: string, metadata?: object}>,
* worktreesRoot: string,
* sourceWorkspace?: string,
* }} input
* @returns {{ existingBranch: string, resumedFromAgentId: string, resumeWorktreePath: string, claimResumeInPlace: true }|null}
*/
export function claimContinuationPointer({ task, agentId, worktrees = [], agents = [], worktreesRoot, sourceWorkspace }) {
if (!hasClaimFlowContract(task)) return null;
const branchName = claimContinuationBranch(task?.metadata?.claimTarget);
if (!branchName || !agentId || !worktreesRoot) return null;
if (!Array.isArray(agents)) return null;
const holder = worktrees.find((wt) => {
const branch = String(wt?.branch || '').replace(/^refs\/heads\//, '');
return branch === branchName && wt?.path && !wt.locked && !wt.prunable;
});
if (!holder) return null;
if (!isHumanClaimWorktree(worktreeAgentId(holder.path))) return null;
if (!isPathInsideDir(worktreesRoot, holder.path)) return null;
// Only a definite owner withholds the pointer. A possible one (a picker run
// in the same repository) is left to `claimContinuationAdmission`, which sees
// the checkout's activity at the moment of launch.
const occupancy = claimHolderOccupancy({
agents, holderPath: holder.path, branchName, sourceWorkspace, ignoreIds: new Set([agentId]),
});
if (occupancy === 'active') return null;
return {
existingBranch: branchName,
resumedFromAgentId: agentId,
resumeWorktreePath: holder.path,
claimResumeInPlace: true,
};
}
/**
* Workspace a relaunch should use when the claim pointer is still valid on
* disk. Null sends the caller down the ordinary prep path.
*
* @param {{ metadata?: object, pathExists?: (path: string) => boolean, worktreesRoot: string }} input
*/
export function claimContinuationWorkspace({ metadata, pathExists = () => false, worktreesRoot }) {
if (metadata?.claimResumeInPlace !== true && metadata?.claimResumeInPlace !== 'true') return null;
const worktreePath = metadata?.resumeWorktreePath;
const branchName = metadata?.existingBranch;
if (!worktreePath || !branchName || !worktreesRoot) return null;
if (!isHumanClaimWorktree(worktreeAgentId(worktreePath))) return null;
if (!isPathInsideDir(worktreesRoot, worktreePath)) return null;
if (!pathExists(worktreePath)) return null;
return {
workspacePath: worktreePath,
worktreeInfo: {
worktreePath,
branchName,
baseBranch: null,
existingBranch: true,
adopted: true,
claimResumeInPlace: true,
},
};
}
/**
* Shared admission for coordinator adoption/release and claim continuations.
* A missing cache may discover the holder; a supplied cache must still match.
* With no holder, branch/repository owners still prevent a new checkout from
* taking over publication while the original run is between worktrees.
*/
export function claimBranchAdmission({ branchName, preferredPath, agentId, sourceWorkspace, worktrees, agents, ignoreIds = [] }) {
if (!Array.isArray(worktrees) || !Array.isArray(agents)) return { admit: false, reason: 'ownership-unreadable' };
if (!branchName) return { admit: false, reason: 'pointer-incomplete' };
const holder = preferredPath
? worktrees.find(wt => samePath(wt?.path, preferredPath))
: worktrees.find(wt => String(wt?.branch || '').replace(/^refs\/heads\//, '') === branchName);
if (preferredPath && !holder) return { admit: false, reason: 'holder-missing' };
if (holder && String(holder.branch || '').replace(/^refs\/heads\//, '') !== branchName) {
return { admit: false, reason: 'branch-changed' };
}
if (holder?.locked || holder?.prunable) return { admit: false, reason: 'holder-locked' };
const occupancy = claimHolderOccupancy({
agents, holderPath: holder?.path, branchName, sourceWorkspace,
ignoreIds: new Set([agentId, ...ignoreIds].filter(Boolean)),
});
if (occupancy === 'active') return { admit: false, reason: 'owner-active' };
if (occupancy === 'ambiguous') return { admit: false, reason: 'owner-ambiguous' };
return { admit: true };
}
/**
* Launch-time ownership admission for an in-place continuation. A pointer is a
* cached answer from when the previous run died; another owner can appear after
* that, so the pointer alone is not authority to enter the checkout. Re-reads
* the holder and the agent registry as supplied by the caller and admits only
* when the same branch is still checked out in the same directory and no other
* live owner holds it. Anything unreadable or changed refuses — the caller
* defers the launch and touches neither ref nor tree.
*
* A live claim run that picks its own branch (a swarm orchestrator whose
* children cut trees PortOS never sees) might own this tree. Nothing observable
* proves it does not — git activity, the continued run's own registration, and
* the absence of a process inside the tree can all be true of a live owner — so
* the launch stays deferred until that run binds the branches it works on (the
* claim prompt binds each before cutting it) or ends.
*
* @param {{
* metadata?: object,
* agentId: string,
* sourceWorkspace?: string,
* worktrees: Array<object>|null,
* agents: Array<object>|null,
* }} input
* @returns {{ admit: true }|{ admit: false, reason: string }}
*/
export function claimContinuationAdmission({ metadata, agentId, sourceWorkspace, worktrees, agents }) {
if (!Array.isArray(worktrees) || !Array.isArray(agents)) return { admit: false, reason: 'ownership-unreadable' };
const branchName = metadata?.existingBranch;
const worktreePath = metadata?.resumeWorktreePath;
if (!branchName || !worktreePath) return { admit: false, reason: 'pointer-incomplete' };
return claimBranchAdmission({
branchName, preferredPath: worktreePath, agentId, sourceWorkspace, worktrees, agents,
ignoreIds: [metadata?.resumedFromAgentId],
});
}
/**
* Why a live claim owner holds this branch's checkout, for a caller about to
* classify, dispatch or mutate it from outside that run (branch-reconcile's
* scan and its worker's pre-mutation recheck). The same branch/repository owner
* contract as `claimBranchAdmission`, without its holder-path bookkeeping: the
* caller already knows the checkout. An unreadable registry holds the branch.
*
* @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(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 { reason: 'claim-ownership-unreadable', owners: [] };
const { occupancy, holderIds } = scanClaimHolders({
agents, holderPath, branchName, sourceWorkspace, ignoreIds: new Set(ignoreIds.filter(Boolean)),
});
return occupancy ? { reason: `claim-owner-${occupancy}`, owners: holderIds } : null;
}