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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
| [`/crucible`](./skills/crucible/SKILL.md) | Parallel multi-candidate design (`sketch`) and prototype (`full`) arena across orthogonal axes (`cand-*`), cross-family `ro-judge` scoring, and donor `cherry-pick` synthesis. |
| [`/interrogate`](./skills/interrogate/SKILL.md) | Adversarial bug hunting (`adv-*` executable repros) combined with transitive caller, schema, and rollout blast-radius mapping (`ro-blast`), gated by `ro-verify`. |
| [`/reflect`](./skills/reflect/SKILL.md) | Post-mortem, user-correction mining, and structural tightening across transcripts and `board.jsonl`, encoding fixes into hooks, capsules, types, lints, tests, or skills. |
| [`/ketchup`](./skills/ketchup/SKILL.md) | Catch-up briefings across `board.jsonl` `#seq` deltas, `members.json`, optional narrator `swarm_view/view.json`, prior sessions, `git log`, and PR status in standard, `--plain`, and `--video` formats. |
| [`/ketchup`](./skills/ketchup/SKILL.md) | Catch-up briefings across `board.jsonl` `#seq` deltas, `members.json`, Swarm UI Overview `plan.json`, optional narrator `view.json`, prior sessions, `git log`, and PR status in standard, `--plain`, and `--video` formats. |
| [`/verify-gen`](./skills/verify-gen/SKILL.md) | Create and `--maintain` project-local behavioral E2E verification skills (`features/` maps) and `--formal` invariant or TLA+ verification skills, proven live by `ro-verify`. |
| [`/control-ui`](./skills/control-ui/SKILL.md) | Local Playwright, browser, and CDP harness craft with per-worker ephemeral ports and isolated `--user-data-dir` profiles so parallel swarm workers never collide. |
| [`/control-cli`](./skills/control-cli/SKILL.md) | Local `tmux`, PTY, and runtime-inspector harness craft with isolated sockets, temp home directories, and deterministic terminal dimensions per worker. |
Expand Down
17 changes: 16 additions & 1 deletion hooks/guard.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -479,12 +479,23 @@ function getAnchorCoordinatorId(doc, ownerDirId) {
if (typeof explicitCoord === "string" && explicitCoord.length > 0) {
return explicitCoord;
}
if (
doc.backend === "local" &&
typeof doc.swarm_id === "string" &&
doc.swarm_id.length > 0 &&
!doc.swarm_id.startsWith("-") &&
REMOTE_SWARM_ID_RE.test(doc.swarm_id)
) {
return doc.swarm_id;
}
return ownerDirId;
}

function parseRemoteSwarmAnchor(doc) {
if (!doc || typeof doc !== "object") return null;
if (typeof doc.backend !== "string" || doc.backend.length === 0) return null;
if (typeof doc.backend !== "string" || doc.backend.length === 0 || doc.backend === "local") {
return null;
}
if (
typeof doc.swarm_id !== "string" ||
doc.swarm_id.startsWith("-") ||
Expand Down Expand Up @@ -746,6 +757,10 @@ function inspectSwarmDirectory(swarmDir, ownerDirId, targetConversationId, conte
return { kind: "anchor_coordinator" };
}

if (anchorDoc?.backend === "local") {
return { kind: "none" };
}

return { kind: "anchor_unresolved" };
}

Expand Down
213 changes: 213 additions & 0 deletions hooks/guard.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2929,6 +2929,219 @@ if (process.env.MOCK_CLI_MODE === "hang") { setTimeout(() => {}, 10000); } else
}
});

test("handles agy 1.5.9 local swarm.json anchors without invoking remote CLI or blocking non-worker-roots cache while preserving remote spanner anchors", () => {
const sb = makeSandbox();
try {
const coordCapsule = readFileSync(join(PLUGIN_ROOT, "roles", "coordinator.md"), "utf8");
const agentCapsule = readFileSync(join(PLUGIN_ROOT, "roles", "poteto-agent.md"), "utf8");
const researchCapsule = readFileSync(join(PLUGIN_ROOT, "roles", "research.md"), "utf8");
const cacheDir = join(sb.appDataDir, "plugin_data", "agy-pstack-next");

const callsLog = join(sb.root, "local-vs-remote-cli-calls.jsonl");
const mockCli = join(sb.root, "mock-swarm-cli.mjs");
writeFileSync(
mockCli,
`#!/usr/bin/env node
import { appendFileSync } from "node:fs";
const args = process.argv.slice(2);
appendFileSync(${JSON.stringify(callsLog)}, JSON.stringify(args) + "\\n", "utf8");
const swarmId = args[args.length - 1];
if (swarmId === "swm_remote_v1") {
process.stdout.write(JSON.stringify({
swarm_id: swarmId,
members: {
coordinator: { conversation_id: "remote-v1-coord", role: "coordinator" },
"ro-1": { conversation_id: "remote-v1-ro", role: "worker" },
},
}) + "\\n");
}
`,
"utf8",
);
chmodSync(mockCli, 0o755);

const writeAnchor = (dirId, doc) => {
const dir = join(sb.appDataDir, "brain", dirId, ".system_generated", "swarm");
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "swarm.json"), JSON.stringify(doc), "utf8");
};

writeAnchor("local-full-coord", {
version: 1,
backend: "local",
swarm_id: "local-full-coord",
created_at: "2026-11-15T08:00:00.000Z",
});
writeSwarmMembers(sb.appDataDir, "local-full-coord", {
coordinator: { conversation_id: "local-full-coord", role: "coordinator" },
"impl-1": { conversation_id: "local-full-impl", role: "worker" },
"ro-1": { conversation_id: "local-full-ro", role: "worker" },
});

assert.deepEqual(
runGuard(
{ hookEventName: "SessionStart", conversationId: "local-full-coord" },
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{ injectSteps: [{ systemMessage: { systemMessage: coordCapsule } }] },
);
assert.deepEqual(
runGuard(
{
hookEventName: "SessionStart",
conversationId: "local-full-impl",
rootConversationId: "local-full-coord",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{ injectSteps: [{ systemMessage: { systemMessage: agentCapsule } }] },
);
assert.deepEqual(
runGuard(
{
hookEventName: "SessionStart",
conversationId: "local-full-ro",
rootConversationId: "local-full-coord",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{ injectSteps: [{ systemMessage: { systemMessage: researchCapsule } }] },
);
assert.equal(
runGuard(
{
hookEventName: "PreToolUse",
conversationId: "local-full-ro",
cwd: sb.worktree,
toolCall: { id: "lr-1", name: "write_file", args: { Path: join(sb.worktree, "blocked.txt") } },
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
).decision,
"deny",
);

writeAnchor("local-orphan-coord", {
version: 1,
backend: "local",
swarm_id: "local-orphan-coord",
created_at: "2026-11-15T08:01:00.000Z",
});
writeAnchor("local-orphan-dir", {
version: 1,
backend: "local",
swarm_id: "local-orphan-coord-alias",
created_at: "2026-11-15T08:01:30.000Z",
});
writeAnchor("plain-local-coord", {
version: 1,
backend: "local",
swarm_id: "plain-local-coord",
created_at: "2026-11-15T08:01:45.000Z",
});

assert.deepEqual(
runGuard(
{ hookEventName: "SessionStart", conversationId: "local-orphan-coord" },
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{ injectSteps: [{ systemMessage: { systemMessage: coordCapsule } }] },
);
assert.deepEqual(
runGuard(
{
hookEventName: "SessionStart",
conversationId: "local-orphan-coord-alias",
rootConversationId: "local-orphan-dir",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{ injectSteps: [{ systemMessage: { systemMessage: coordCapsule } }] },
);
assert.deepEqual(
runGuard(
{
hookEventName: "SessionStart",
conversationId: "plain-local-coord",
lastUserInput: "/swarm local plain title",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{},
);
assert.deepEqual(
runGuard(
{ hookEventName: "SessionStart", conversationId: "unrelated-conv" },
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{},
);
assert.equal(existsSync(callsLog), false, "local swarm.json must never invoke remote CLI");

const nonWorkersAfterLocalOrphan = existsSync(join(cacheDir, "non-worker-roots.json"))
? JSON.parse(readFileSync(join(cacheDir, "non-worker-roots.json"), "utf8"))
: {};
assert.equal(nonWorkersAfterLocalOrphan["unrelated-conv"], true);

writeAnchor("remote-v1-coord", {
version: 1,
backend: "spanner",
swarm_id: "swm_remote_v1",
created_at: "2026-11-15T08:02:00.000Z",
db: "projects/p/instances/i/databases/d",
coordinator_conversation_id: "remote-v1-coord",
});
assert.deepEqual(
runGuard(
{
hookEventName: "SessionStart",
conversationId: "remote-v1-ro",
rootConversationId: "remote-v1-coord",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{ injectSteps: [{ systemMessage: { systemMessage: researchCapsule } }] },
);
const callsAfterRemoteResolved = readFileSync(callsLog, "utf8")
.trim()
.split("\n")
.map((line) => JSON.parse(line));
assert.equal(callsAfterRemoteResolved.length, 1);
assert.deepEqual(callsAfterRemoteResolved[0], [
"swarm",
"--json",
"--roster-only",
"--db",
"projects/p/instances/i/databases/d",
"swm_remote_v1",
]);

writeAnchor("remote-missing-coord", {
version: 1,
backend: "spanner",
swarm_id: "swm_remote_missing",
created_at: "2026-11-15T08:03:00.000Z",
coordinator_conversation_id: "remote-missing-coord",
});
assert.deepEqual(
runGuard(
{
hookEventName: "SessionStart",
conversationId: "remote-unresolved-conv",
rootConversationId: "remote-missing-coord",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir, PSTACK_REMOTE_SWARM_CLI: mockCli },
),
{},
);
const nonWorkersAfterRemoteUnresolved = existsSync(join(cacheDir, "non-worker-roots.json"))
? JSON.parse(readFileSync(join(cacheDir, "non-worker-roots.json"), "utf8"))
: {};
assert.equal(nonWorkersAfterRemoteUnresolved["remote-unresolved-conv"], undefined);
} finally {
sb.cleanup();
}
});

test("allows multi-argument Python str.replace in inline scripts while blocking 1-arg Path.replace and escaping rename or replace targets", () => {
const sb = makeSandbox();
try {
Expand Down
8 changes: 4 additions & 4 deletions skills/ketchup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ description: >-
plain-language restatements (--plain), subtitled slide walkthrough videos
(--video), and cross-session transcript and swarm recall (--recall). Parallel
read-only ro-* gatherers inspect board.jsonl #seq deltas, members.json,
optional narrator view.json, prior swarm boards, git log, and gh pr
state. Use for /agy-pstack-next:ketchup, /ketchup, "catch me up",
Swarm UI Overview plan.json, optional narrator view.json, prior swarm boards,
git log, and gh pr state. Use for /agy-pstack-next:ketchup, /ketchup, "catch me up",
"ketchup --plain", "explain that in plain words", "ketchup --video", "recall
my work on X", or "where did I leave off".
---
Expand All @@ -32,9 +32,9 @@ Keep the repository completely read-only in every mode. Rendering the MP4 into `

Never trust stale prose in chat when live state can be checked. For small single-turn catch-ups, inspect directly. Whenever a swarm ran, multiple PRs or branches moved, or `--recall` spans prior sessions, spawn parallel read-only `ro-*` gatherers (`workspace: "inherit"`, enforced read-only by `hooks/guard.mjs`) using the `ro-*` model from `~/.gemini/config/rules/pstack-models.md` (or `inherit`):

- **`ro-swarm` (live swarm and board delta).** Inspects `<appDataDir>/brain/<conversation-id>/.system_generated/swarm/` (`members.json` roster states and worktree paths, `swarm.json`, and `board.jsonl` `#seq` deltas since the human's last message) alongside `swarm{action: "status"}`. For narrator Overview state, checks `<appDataDir>/brain/<conversation-id>/.system_generated/swarm/view.json` first, and otherwise selects the highest-numbered live `narrator` or `narrator-N` replacement (`narrator` ranks `1`, `narrator-N` ranks `N`) ahead of any killed narrator entry in `members.json` before reading `<appDataDir>/brain/<narrator-id>/swarm_view/view.json` if present. Because `swarm_narrator` is optional and absent in `agy` CLI sessions, `ketchup` falls back cleanly to `board.jsonl` and `members.json` whenever no `narrator` or `view.json` exists. Verifies claimed worker completions against real commits and test runs.
- **`ro-swarm` (live swarm and board delta).** Inspects `<appDataDir>/brain/<conversation-id>/.system_generated/swarm/` (`members.json` roster states and worktree paths, `swarm.json`, and `board.jsonl` `#seq` deltas since the human's last message) alongside `swarm{action: "status"}`. For Swarm UI Overview state, checks `<appDataDir>/brain/<conversation-id>/.system_generated/swarm/plan.json` (goal, tasks, and outcome threads written when `swarm_pane` is active in `<skills>`) and `Screenshot: <abs_path> | <caption>` lines on `board.jsonl`. For optional narrator state, checks `<appDataDir>/brain/<conversation-id>/.system_generated/swarm/view.json` first, and otherwise selects the highest-numbered live `narrator` or `narrator-N` replacement (`narrator` ranks `1`, `narrator-N` ranks `N`) ahead of any killed narrator entry in `members.json` before reading `<appDataDir>/brain/<narrator-id>/swarm_view/view.json`. Because `swarm_pane` and `swarm_narrator` are omitted from `<skills>` in `agy` CLI sessions, `ketchup` falls back cleanly to `board.jsonl` and `members.json` whenever neither `plan.json` nor `view.json` exists. Verifies claimed worker completions against real commits and test runs.
- **`ro-repo` (live git, PR, and CI state).** Runs `git status --short`, `git branch`, `git log`, and `gh pr list` / `gh pr view` / `gh pr checks` to confirm branch cleanliness, review threads, merge readiness, and exact numbers behind any metric before reporting it.
- **`ro-history` (cross-session transcripts, prior swarms, and shared record for `--recall`).** Orders `<appDataDir>/brain/*` directories strictly within the active workspace by real modification time (`ls -t`, default 7-day window unless another window is named). Filters matching topics first, reads `<appDataDir>/brain/<id>/.system_generated/logs/transcript.jsonl` (`transcript_full.jsonl` only on `truncated_fields` lines), prior `<appDataDir>/brain/<id>/.system_generated/swarm/` (`members.json` and `board.jsonl`), and narrator Overview `view.json` by checking `<appDataDir>/brain/<id>/.system_generated/swarm/view.json` first and otherwise selecting the highest-numbered live `narrator` or `narrator-N` replacement ahead of any killed narrator entry in `members.json` before reading `<appDataDir>/brain/<narrator-id>/swarm_view/view.json`, skipping unrelated workspaces or eval noise. When `--recall` names a feature, module, or bug, also queries issue trackers, docs, chat, and error telemetry per [`../understand/references/source-playbook.md`](../understand/references/source-playbook.md) to surface reverts and recurring user reports.
- **`ro-history` (cross-session transcripts, prior swarms, and shared record for `--recall`).** Orders `<appDataDir>/brain/*` directories strictly within the active workspace by real modification time (`ls -t`, default 7-day window unless another window is named). Filters matching topics first, then reads `<appDataDir>/brain/<id>/.system_generated/logs/transcript.jsonl` (`transcript_full.jsonl` only on `truncated_fields` lines) and prior `<appDataDir>/brain/<id>/.system_generated/swarm/` (`members.json`, `board.jsonl` including `Screenshot: <abs_path> | <caption>` lines, and `plan.json` goal, tasks, and outcome threads written when `swarm_pane` is active in `<skills>`), skipping unrelated workspaces or eval noise. Also inspects optional narrator `view.json` by checking `<appDataDir>/brain/<id>/.system_generated/swarm/view.json` first and otherwise selecting the highest-numbered live `narrator` or `narrator-N` replacement ahead of any killed narrator entry in `members.json` before reading `<appDataDir>/brain/<narrator-id>/swarm_view/view.json`. When `--recall` names a feature, module, or bug, also queries issue trackers, docs, chat, and error telemetry per [`../understand/references/source-playbook.md`](../understand/references/source-playbook.md) to surface reverts and recurring user reports.

Retire all `ro-*` gatherers via `swarm{action: "kill"}` once their `#seq` reports arrive.

Expand Down
Loading