Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1663,6 +1663,7 @@ quest agent start --harness claude --model claude-opus-5-5 --effort high --permi
quest agent resume --harness claude --model claude-opus-5-5 --effort high --permission-mode auto .worktrees/foo <session> "Take the recommendation."
quest agent stop .worktrees/foo
quest agent stop --all
quest agent admit
```

Codex starts and resumes only in a checkout registered by `quest worktree create`,
Expand All @@ -1676,6 +1677,20 @@ pruned dependencies when the next turn needs them. Claude continues to run
directly in the supplied checkout. Codex desktop threads use the desktop app's
native archival instead.

Start and resume first wait until the host can carry one more agent, before
claiming the worktree, and a coordinator runs `quest agent admit` before it
starts or resumes a sub-agent of its own. The host has room while `quest gate`
would admit a command at once, counting every command queued for it and, as one
recent admission each, every agent admitted in the last 5 minutes: an agent adds
no gated load until its first build, and three quarters of those that build at
all reach it by then. An agent `start` or `resume` runs stops counting when it
exits. As in the gate, a host loaded only by work no gate holds still starts one
agent at a time.

Admission only delays the next agent: none already running is paused or
stopped, and `quest agent stop` does not see a launch still waiting, which ends
when its command is cancelled.

Options go before the worktree, and the prompt or message follows it, so text
starting with `-` is never read as an option. The agent runs in the worktree
with the user's environment minus the coordinating session's harness variables
Expand Down
3 changes: 2 additions & 1 deletion assets/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,8 @@ Relay no interim report: resume a sub-agent that ended its turn on one, telling
A long-running coordinator lets compaction bound its context: what must outlast it lives in the forge and the quest tree, and a PR's state is read afresh before acting, not trusted from earlier turns.

Start each sub-agent in the background with its own isolated worktree, since agents cannot write to a worktree their parent created.
It reports only when done or blocked, and never waits on GitHub CI, reviews, or merges; stay silent on its interim notifications.
Before starting or resuming one, run `quest agent admit` in the background and go on once it exits 0, handling reports meanwhile: it waits until the host has room for another agent. `quest agent start` and `resume` admit themselves.
A sub-agent reports only when done or blocked, and never waits on GitHub CI, reviews, or merges; stay silent on its interim notifications.
As each reports, explain its result in a few lines: its PR, whether it is still a draft, and its open decisions with recommendations.
Once two agents report the same blocker, such as a check failure that reproduces on the base or a reviewer outage, name it with its evidence in each later agent's brief, and report it once.

Expand Down
2 changes: 1 addition & 1 deletion assets/CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Before ending a task, pausing for a decision, or handing off, commit a checkpoin
Finish with a clean checkout: intended changes committed and pushed, incidental generated changes restored, and pre-existing or unrelated changes preserved.

Run CPU-heavy commands, such as builds, tests, model checkers, and browsers, through `quest gate <command>`, which queues until the host has room; model calls like `quest review` and servers stay out.
Never work around the queue by polling the load average or capping agents yourself; cancel a gated command only when you no longer need its result.
Never work around the queue by polling the load or capping agents, `quest agent admit`'s job; cancel a gated command only once its result is unneeded.
Run it in the foreground and read its exit code directly, not through a pipe.
Never end a turn or report while your background work runs, and never poll it with `sleep` or status checks: block on it with the harness's own wait for that task, at the longest interval it allows, saying nothing between waits.
To wait on a PR's CI or reviews, use `quest wait`, re-running one that times out with the `--since` it printed, so activity during the first wait is still reported.
Expand Down
2 changes: 1 addition & 1 deletion assets/skills/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ A brief gives the task, its reason and context, such as the quest or PR and the

Starting quests asks the user nothing: each agent works headless, and its decisions surface in its PR.

`quest unblocked --unclaimed --json` ranks the unclaimed ready quests, reading the upstream tree afresh; start them in that order, as many at once as the harness allows.
`quest unblocked --unclaimed --json` ranks the unclaimed ready quests, reading the upstream tree afresh; start them in that order, each once `quest agent admit` admits it, as the guide's Coordination section describes.
It lists each skipped claim on stderr, with how long ago it was last active when it has an open PR; name any that look stale in the summary, for the user to take over.

Start every quest you would recommend: well planned, with no blockers, and no conflict with work already started. For one waiting on an outside condition, first check whether it has cleared.
Expand Down
2 changes: 1 addition & 1 deletion docs/context.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Before ending a task, pausing for a decision, or handing off, commit a checkpoin
Finish with a clean checkout: intended changes committed and pushed, incidental generated changes restored, and pre-existing or unrelated changes preserved.

Run CPU-heavy commands, such as builds, tests, model checkers, and browsers, through `quest gate <command>`, which queues until the host has room; model calls like `quest review` and servers stay out.
Never work around the queue by polling the load average or capping agents yourself; cancel a gated command only when you no longer need its result.
Never work around the queue by polling the load or capping agents, `quest agent admit`'s job; cancel a gated command only once its result is unneeded.
Run it in the foreground and read its exit code directly, not through a pipe.
Never end a turn or report while your background work runs, and never poll it with `sleep` or status checks: block on it with the harness's own wait for that task, at the longest interval it allows, saying nothing between waits.
To wait on a PR's CI or reviews, use `quest wait`, re-running one that times out with the `--since` it printed, so activity during the first wait is still reported.
Expand Down
96 changes: 0 additions & 96 deletions quest/m0/agent-admission.md

This file was deleted.

62 changes: 0 additions & 62 deletions quest/m0/gate-memory.md

This file was deleted.

94 changes: 94 additions & 0 deletions src/cli/admission.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
// Agent admission: a coordinator starts or resumes an agent only while the host's gate would admit
// work at once. It only delays the next start: agents already running are never paused or stopped.
import { randomUUID } from "node:crypto";
import { basename, dirname, join } from "node:path";

import {
type Admission,
type Host,
type Limits,
SETTLE_MS,
type Waiting,
claimDirectory,
fileHost,
hostLimits,
processStart,
room,
} from "./gate";

/**
* How long an admitted agent counts against the host's headroom, as one recent admission of the
* gate's: an agent adds no gated load until its first build. Of 263 sub-agents on one host over three
* weeks, the 126 that gated anything reached their first gated command in a median of 133 seconds,
* and three quarters within 265; the rest never gated, so no later event ends the count.
*/
export const PENDING_MS = 5 * 60_000;

/** What `admit` reads and writes, replaceable in tests. */
export interface AdmissionDependencies {
limits: Limits;
/** The gate's ledger and the host's load and memory. */
gate: Host;
/** The agents' ledger; only its clock, ledger, liveness, and sleep are used. */
agents: Host;
/** A line for the user. */
notice(text: string): void;
}

const waits: Record<Waiting, string> = {
load: "the load average to fall",
memory: "free memory",
queue: "gated commands queued on this host to start",
};

/**
* Wait until the host can carry one more agent, then record it. The host has room while the gate
* would admit a command at once (see `room`), counting each agent admitted in the last PENDING_MS
* whose launcher, if it has one, still runs.
*
* `held` is the process that runs the agent, as `quest agent start` does; without it, as for a
* coordinator's own sub-agent, nothing reports the agent's end.
*/
export async function admit(deps: AdmissionDependencies, signal: AbortSignal, held?: number): Promise<void> {
const holder = held === undefined ? {} : { pid: held, start: processStart(held) };
const shown = new Set<Waiting>();
for (;;) {
signal.throwIfAborted();
const ledger = deps.agents.ledger();
const now = deps.agents.now();
// A clock stepped backward dates an entry in the future; restart it from now, so it still expires.
if (ledger.admissions.some((entry) => entry.at > now)) {
deps.agents.publish(
ledger,
ledger.admissions.map((entry) => (entry.at > now ? { ...entry, at: now } : entry)),
);
continue;
}
const pending = ledger.admissions.filter(
(entry) => entry.at > now - PENDING_MS && (entry.pid === undefined || deps.agents.running(entry)),
);
const reason = room(deps.limits, deps.gate, pending.length);
if (reason === null) {
const entry: Admission = { id: randomUUID(), at: now, ...holder };
if (deps.agents.publish(ledger, [...pending, entry])) return;
continue;
}
if (!shown.has(reason)) {
shown.add(reason);
deps.notice(`waiting for ${waits[reason]} before starting an agent`);
}
await deps.agents.sleep(SETTLE_MS, signal);
}
}

/** The agents' ledger of this host, beside the gate's. */
const agentsDirectory = (gate: string) => join(dirname(dirname(gate)), "agents", basename(gate));

/** The admission `quest agent` runs with: the host's own limits and ledgers. */
export function processAdmission(notice: (text: string) => void): AdmissionDependencies {
const gate = claimDirectory();
return { limits: hostLimits(), gate: fileHost(gate), agents: fileHost(agentsDirectory(gate)), notice };
}

/** The admission every `quest agent` command runs, held in an object so a test can replace it. */
export const admission = { admit };
Loading
Loading