Add Stop with a handoff, handoff chips on the dashboard, and a one-step delete for fixed bugs

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-17 12:35:29 -07:00
1 parent 33a0dbd34a
commit 36843e4bc9
34 files changed
+1926 -267

No files matched your search

@@ -1,107 +0,0 @@
#!/usr/bin/env node
// handoff-path.mjs: where the handoff document goes, and whether git would pick it up.
//
// The handoff skill names its file <dir>/<YYYY-MM-DD-HHmm>-handoff.md, takes the
// timestamp from the clock rather than a guess, creates the folder, and checks
// whether the file would be tracked by git (is this a repo, is the path
// ignored). That is a fixed sequence with one right answer per machine, so it
// lives here. Whether to add an ignore line is the user's call.
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { execFileSync } from "node:child_process";
import { EXIT, fail, out, parseArgs, run, isoDate, now } from "./common.mjs";
const USAGE = `
handoff-path.mjs: pick the handoff file path and check it against git. JSON on stdout.
node handoff-path.mjs [--dir temp|<path>] [--root <dir>] [--dry-run]
--dir temp (the default): the OS temporary directory. Anything else is a
folder, relative to --root (default: the current directory), e.g.
handoffs (a project folder literally named temp: ./temp).
Created if missing (not with --dry-run).
Prints { path, dir, created, timestamp, git: { repo, inRepo, ignored,
ignoreLine }, warning? }. The file name is <YYYY-MM-DD-HHmm>-handoff.md; if one
already exists for this minute, -2, -3... is appended so earlier handoffs are
never overwritten. git.ignored is null when the file is outside a repo (nothing
to ignore); false means it would show up in git status, and then git.ignoreLine
is the .gitignore line to offer and the top-level warning says so.
Exit: 0 ok · 2 bad arguments · 5 the folder cannot be created, or --dir names
an existing file (not-a-folder).
`;
function git(cwd, args) {
try {
return { ok: true, out: execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim() };
} catch (err) {
return { ok: false, status: err.status };
}
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["dir", "root"] });
const root = path.resolve(args.root || ".");
const choice = args.dir || "temp";
const dir = choice === "temp" ? os.tmpdir() : path.resolve(root, choice);
let created = false;
if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {
fail(EXIT.REFUSED, "not-a-folder", `${dir} exists and is a file, not a folder.`, "Pass a folder for --dir (a new one is created), or use --dir temp.");
}
if (!fs.existsSync(dir)) {
if (!args["dry-run"]) {
try {
fs.mkdirSync(dir, { recursive: true });
created = true;
} catch (err) {
fail(EXIT.REFUSED, "mkdir-failed", `Could not create ${dir}: ${err.message}`, "Pick another folder, or use --dir temp.");
}
}
}
const d = now();
const pad = (n) => String(n).padStart(2, "0");
const timestamp = `${isoDate(d)}-${pad(d.getHours())}${pad(d.getMinutes())}`;
let file = path.join(dir, `${timestamp}-handoff.md`);
for (let n = 2; fs.existsSync(file); n++) file = path.join(dir, `${timestamp}-${n}-handoff.md`);
// Compare real paths: git prints the repo's real top level, while the folder
// may arrive as an 8.3 short name (C:\Users\JOHN~1\...) or through a symlink
// (macOS /tmp -> /private/tmp). A folder not created yet (--dry-run) resolves
// through its nearest existing ancestor. Git runs from that ancestor too, so
// the file is checked against the repo it would actually land in.
const existing = (() => {
let p = dir;
while (!fs.existsSync(p) && path.dirname(p) !== p) p = path.dirname(p);
return p;
})();
const realDir = path.join(fs.realpathSync.native(existing), path.relative(existing, dir));
const realFile = path.join(realDir, path.basename(file));
const top = git(existing, ["rev-parse", "--show-toplevel"]);
const gitInfo = { repo: top.ok || git(root, ["rev-parse", "--show-toplevel"]).ok, inRepo: false, ignored: null };
if (top.ok) {
const repoRoot = fs.realpathSync.native(path.resolve(top.out));
const relToRepo = path.relative(repoRoot, realFile);
gitInfo.inRepo = !!relToRepo && !relToRepo.startsWith("..") && !path.isAbsolute(relToRepo);
if (gitInfo.inRepo) {
// check-ignore exits 0 when ignored, 1 when not; it honours global and nested ignore files.
const ci = git(repoRoot, ["check-ignore", "-q", relToRepo.split(path.sep).join("/")]);
gitInfo.ignored = ci.ok;
const relDir = path.relative(repoRoot, realDir).split(path.sep).join("/");
// The repo root itself is never the line to ignore: offer the handoff files instead.
gitInfo.ignoreLine = relDir ? `${relDir}/` : "*-handoff.md";
}
}
out({
ok: true,
path: file,
dir,
created,
dryRun: !!args["dry-run"],
timestamp,
git: gitInfo,
...(gitInfo.inRepo && gitInfo.ignored === false ? { warning: `This file would be tracked by git. Offer to add "${gitInfo.ignoreLine}" to .gitignore; do not add it without asking.` } : {}),
});
});
+4 -24
View File
@@ -38,28 +38,15 @@ the next task (and shape the whole document around it), but still confirm.
## Where to write it
Ask the user if they would like to save the file to the temporary directory of the user's OS (this should be the default) or to some other location like `./handoffs/` at the repo root. Then let the script pick the exact path, from the project root:
No question to ask: every handoff lives in `~/.plan2code/handoffs/`, outside every repo. From the project root, let the console name the file:
```
node "<S>/handoff-path.mjs" --dir temp # or: --dir handoffs
node "<D>/console.mjs" handoff new --workflow handoff --skill plan2code-handoff --spec specs/<feature> --title "<short title>"
```
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-handoff/scripts/` globally). It prints one JSON object: `path` is `<dir>/<YYYY-MM-DD-HHmm>-handoff.md` from the clock (suffixed `-2`, `-3`... rather than overwrite an earlier handoff), and the folder is created if missing. Write the document to exactly that `path`. Exit 5 means the folder could not be created (or `--dir` names a file): ask for another location.
`<D>` is `references/web-console/` beside this SKILL.md, as in Interface. Pass `--spec` only when the work was inside a spec; the title is a few words naming the work. It prints one JSON object: write the document to exactly its `path`, and tell the person that path. Exit 3 means it could not write there: say so and stop.
### Make sure you aren't leaking the file into version control
The handoff is working state for the next session, not a project artifact, so it
should stay out of commits and PRs. Don't assume it will — this skill may run in
any repo. The same output's `git` block says:
- `repo: false`, or `inRepo: false` (the OS temp dir): nothing to ignore; just tell the user where the file is.
- `ignored: true`: git already ignores it (via any `.gitignore`, global or nested; `git check-ignore` is the check).
- `ignored: false`: it would be tracked; `git.ignoreLine` is the line to offer, and the top-level `warning` says so.
If it is **not** ignored, do not silently modify the user's `.gitignore`. Tell
them the file would be tracked by git and offer to add the `ignoreLine` (e.g.
`handoffs/`) to `.gitignore` — let them decide. Some users may want handoffs committed so
teammates get them; that's a legitimate choice, so present it, don't force it.
The dashboard lists the handoff for this checkout until it is picked up, and old ones go after 30 days.
## If this touched a plan2code spec
@@ -142,10 +129,3 @@ lives (env var name, secret manager entry) rather than its value.
Tell the user the path you wrote to and give a one-line summary of the confirmed
next task, so they know what the incoming agent will start on. Mention that a
fresh session can be pointed at the file to resume the work.
If your ignore check above found the file is in a repo and **not** gitignored
(`git.ignored: false`, which includes a repo with no `.gitignore`), say so plainly
here, e.g. "note: `handoffs/` isn't gitignored in this repo, so this file will
show up in `git status` and could be committed", and offer to add the
`ignoreLine`. Outside a repo there is nothing to ignore. Never leave
the user unaware that the handoff might ride along into a commit.
+10 -1
View File
@@ -37,6 +37,7 @@ The page draws the cards itself — you never send the list. It also knows the r
- A `diagnosed` spec ("Bug diagnosed") is a bug Diagnose wrote up: recommend Quick Task, or Plan when its `DIAGNOSIS-<date>.md` sizes the fix as big; its folder rides along on either launch.
- A `fixed` spec ("Bug fixed") is a diagnosed bug Quick Task fixed but did not archive: finished, so never recommend for it or name it in the note; the picker never pre-selects one and hides it while unavailable workflows are hidden. The person archives it (Quick Task offers that once the bug is fixed) or deletes it with the picker's ✕.
- Nothing on disk, or only `fixed` specs → `recommend: "plan2code-0-pathfinder"`; the note invites the first idea.
- A handoff in `state.scan.handoffs` newer than the most recently touched spec is usually the place to start: say so in `note` (the page has no card to `recommend` for it).
- Recommend only what you would tell a person who asked "where do I start?". When in doubt, no flag and a neutral note — the page falls back to flagging the selected spec's own next step.
- `recommend` must name a lit card for the initial selection. If the person switches specs or starts fresh, the page derives the suggestion and detail from its scan instead.
@@ -58,7 +59,7 @@ Ground truth for menu notes and Ask-tab answers. For anything beyond this table,
| 3-implement(-review) | `overview.md`, `phase-X.md` | code; `[x]` marks + completion summary in `phase-X.md` |
| review | spec, diff | the fixes picked; no spec writes |
| 4-finalize | spec + code | summary in `overview.md`; moves the spec to `specs--completed/` |
| handoff | conversation, spec, git | `<timestamp>-handoff.md` (OS temp or `handoffs/`) |
| handoff | conversation, spec, git | `~/.plan2code/handoffs/<id>.md`, listed on the dashboard |
| changelog | `CHANGELOG.md`, `package.json`, git history | `CHANGELOG.md` entries, `package.json` version; no commits |
| git | git status, branches, diffs, `AGENTS.md` | commits, branches; optional `.gitignore`, push, publish; no spec writes |
| xray | the codebase, `git` history, `gh` when present | an answer; `ARCHITECTURE-BRIEF-<date>.md` or `XRAY-<area>-<date>.md` when asked |
@@ -107,6 +108,10 @@ If `skill` is not in the table below, say so on the page and stay the dashboard.
| plan2code-git | git | | plan2code-changelog | changelog |
| plan2code-xray | xray | | plan2code-diagnose | diagnose |
## A pick-up arrives
A handoff chip's **Pick it up here** sends `__pickup` with `resume`, `skillFile` and `handoffFile` (and `fallback` when the named skill or spec is gone, or the Handoff skill wrote it). Read `console-launches.md` → A pick-up, then do as a pick does: `resume` first, then the skill's file, then the handoff.
## A delete arrives
The ✕ on a picker chip asks for that spec to go, after a two-step confirm on the page: `{ "i": "__delete", "type": "delete", "spec": "specs/<name>" }`. The page never deletes; you do, through the console's checked command, never your own `rm`:
@@ -115,6 +120,10 @@ The ✕ on a picker chip asks for that spec to go, after a two-step confirm on t
2. `node "<D>/console.mjs" open --resume <sid> --no-open --workflow dashboard`, which rescans `specs/`.
3. Post the menu again with `--wait`; the note says what was deleted, or why it was not. Stay the dashboard.
A `fixed` spec is deleted after one confirm on the page (its own Delete button, no name to type); your steps are the same.
A handoff's Delete is the same `__delete` with `handoff` (an id) instead of `spec`: run `node "<D>/console.mjs" delete-handoff --handoff <action.handoff>`, then steps 2 and 3.
## Coming back from another skill
You arrive here mid-conversation after a `__dashboard` press — from a finished screen, or mid-workflow from the top bar's triangle once that skill saved its place — having already run `open --resume <sid> --no-open --workflow dashboard` (the send's `resume`; it cleared the last skill's page, its finish included — console-finish.md, console-stop.md). Skip Interface steps 1–2; your first job is the menu judgment, then post the menu with `--wait`: re-read `state.scan`, which the resume refreshed — the spec you just worked on is usually the most recently touched. Then the usual wait loop and launches.
+1 -1
View File
@@ -119,8 +119,8 @@ review set it to its own stage):
"items": [{ "id": "signoff", "status": "reopened",
"body": "Reviewed and ready for sign-off. The review found 3 issues: 2 fixed, 1 still open in the Review findings tab. The report is updated.",
"verdicts": [
{ "id": "show", "label": "Show me it working" },
{ "id": "approve", "label": "Approve this phase" },
{ "id": "show", "label": "Show me it working" },
{ "id": "changes", "label": "I want changes" }
],
"token": { "approve": "approved", "changes": "needs changes", "show": "show me" },
+34 -1
View File
@@ -47,7 +47,7 @@ first, and post before anything slow.
## What the page already knows
`state.scan` is `{ hasAgents, isGit, pending, specs: [{ dir, name, state, detail, touched }] }`,
`state.scan` is `{ hasAgents, isGit, pending, specs: [{ dir, name, state, detail, touched }], handoffs, handoffsDir }`,
a snapshot of the last `open` (a spec created mid-session appears the next time
the session resumes as a dashboard). `pending` is how many files a commit would
take (`null` when git cannot say): the Git card never greys out, shows the count
@@ -64,6 +64,34 @@ person's turn by itself.
A `__stop` before a pick ends the session the usual way: `finish` (paused
headline, `"command": "/plan2code"`) then `stop` (`console-stop.md`).
`handoffs` is this checkout's unused handoffs, newest first (`[{ id, title,
next, written, spec, skill, workflow }]`, read from `~/.plan2code/handoffs/`
by `open`, a dashboard only), and `handoffsDir` is that folder. The picker shows
them as dashed **Handoff** chips after the specs.
## A pick-up
Selecting a handoff chip shows a preview and hides the skill cards. **Pick it up
here** sends a hop like a launch, naming only the id:
```jsonc
{ "type": "submit",
"actions": [{ "i": "__pickup", "type": "pickup", "handoff": "2026-10-17-1152-handoff" }],
"reply": "Pick up the handoff \"Lunch vote\" right here in this session.",
"resume": "node \"…/console.mjs\" open --resume <sid> --no-open --workflow quick-task --spec specs/lunch-vote",
"skillFile": "…/plan2code-quick-task/SKILL.md",
"handoffFile": "~/.plan2code/handoffs/2026-10-17-1152-handoff.md" }
```
`wait` has already read the handoff's stored skill and spec, marked the handoff
used (the next scan no longer lists it) and put the command in `resume`. Run
`resume`, read `skillFile` with your file-read tool, then read `handoffFile`,
follow the skill from where its real work starts, and carry on from the
handoff's **Next task**. When the send carries `"fallback": true` the named
skill or spec was gone, or the Handoff skill wrote it: say so in one line,
since Quick Task is picking it up.
The handoff's document stays on disk until the 30-day sweep.
## A delete
The ✕ on a picker chip, after the page's two-step confirm (what goes, then
@@ -78,3 +106,8 @@ having touched nothing, and drops the workspace remembered for that spec.
Then `open --resume <sid> --no-open --workflow dashboard` to rescan, and post
the menu again with `--wait`, its note saying what went or why it did not.
The page shows the chip as "Deleting…" until that rescan lands.
A handoff's **Delete** sends the same `__delete`, with `handoff` (its id) where a
spec has `spec`. Delete it through
`node "<CONSOLE>" delete-handoff --handoff <id>` (exit 3 with `message` when it
refuses, nothing touched), then rescan and post the menu as for a spec.
+35
View File
@@ -43,6 +43,41 @@ you are halfway through writing their last answers. The one exception is an
agent that has stopped checking in: then Stop comes back, and the request waits
on disk for whichever session collects it next.
## Stop with a handoff
Off the dashboard, the Stop dialog offers **Stop with a handoff** first and
**Just stop and save** second. The handoff choice sends the same `__stop`, with
`handoff: true`, and `wait` adds `handoffSkill` (the Handoff skill's `SKILL.md`,
present in a built skill):
```jsonc
{ "type": "submit",
"actions": [ /* staged answers and notes, as usual */,
{ "i": "__stop", "type": "stop", "handoff": true } ],
"reply": "...the answer lines...\nStop here, save my place and write a handoff, so the dashboard can pick this up later.",
"handoffSkill": "…/plan2code-handoff/SKILL.md" }
```
Act on it in this turn, in this order:
1. **Handle the answers** exactly as in "Stop requests" step 1.
2. **Save your place** exactly as step 2 there.
3. **Make the handoff file:**
`node "<CONSOLE>" handoff new --workflow <yours> --skill <your skill> [--spec <spec>] --title "<short title>" --from-stop`
It prints the `path` to write.
4. **Write the handoff.** Open `handoffSkill` with your file-read tool (never a
skill-invocation tool) and write the document it describes to that `path`.
Skip its questions and its "Where to write it" step: infer the Next task
from where the work stands, and say in the document that it was inferred.
5. **Post `finish`** (`console-finish.md`) with a headline starting "Paused", a
`body` that names the handoff path and says the dashboard will offer it, and
the resume command, without `--wait`.
6. **`stop`** the server.
With no `handoffSkill` (a source checkout), use the structure in
`~/.agents/skills/plan2code-handoff/SKILL.md`. Do not ask whether they are
sure: the page already asked.
## Back to the dashboard, mid-workflow
On every workflow but the dashboard, a triangle left of Stop session takes the
+1 -1
View File
@@ -161,7 +161,7 @@ An action whose `i` starts with `__` is about the session, not a question:
| Action | Read |
| --- | --- |
| `__stop`, `__dashboard` (no finish up) | `console-stop.md` |
| `__stop` (plain, or with `handoff: true`), `__dashboard` (no finish up) | `console-stop.md` |
| `__commit`, `__dashboard` (from a finished screen) | `console-finish.md` |
| `__launch` | `console-launches.md` |
| `__delete` | `console-launches.md` (the dashboard only) |
+132 -10
View File
@@ -99,6 +99,7 @@ import {
writeWorkspaceCursor,
} from "./lib.mjs";
import { snapshot } from "./git-repo.mjs";
import { handoffsDir, isHandoffId, listHandoffs, markHandoffUsed, newHandoff, readHandoffMeta, removeHandoff, removeHandoffs, staleHandoffs } from "./handoffs.mjs";
import { RUN_EVENTS, TASK_EVENTS, MAX_COMMITS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
import { blockFor, offered } from "./public/subagents.js";
import { changeLine } from "./public/workspace.js";
@@ -321,6 +322,13 @@ async function cmdOpen() {
// own top level: `project` is the common-dir key so linked worktrees share
// sessions, but each shows the specs on its own disk.
const scan = state.workflow === "dashboard" ? scanProject(worktree) : null;
// This checkout's unused handoffs live outside every repo (handoffs.mjs), so
// they join the scan here and not in scanProject(), which also serves
// `specs.mjs list`. handoffsDir rides along so the page never guesses it.
if (scan) {
scan.handoffs = listHandoffs(worktree);
scan.handoffsDir = handoffsDir();
}
// The git board's data, the same way: the console's own read-only snapshot
// (git-repo.mjs), taken before the lock so no git process runs under it.
const gitSnap = state.workflow === "git" ? snapshot(worktree, { prHosts: readPrHosts() }) : null;
@@ -384,14 +392,16 @@ async function cmdOpen() {
// Nothing about this reaches the page.
const sweptSessions = staleSessions(SESSIONS_DIR, Date.now(), SESSION_MAX_AGE_MS, sid);
const sweptScratch = staleScratch(HOME_DIR, Date.now(), SESSION_MAX_AGE_MS);
const sweptHandoffs = staleHandoffs(Date.now(), SESSION_MAX_AGE_MS);
const swept =
sweptSessions.length || sweptScratch.length
? { swept: { sessions: sweptSessions, scratch: sweptScratch } }
sweptSessions.length || sweptScratch.length || sweptHandoffs.length
? { swept: { sessions: sweptSessions, scratch: sweptScratch, handoffs: sweptHandoffs } }
: {};
const sweep = () => {
sweepUploads(SESSIONS_DIR, Date.now(), UPLOAD_MAX_AGE_MS, sid).catch(() => {});
removeSessions(SESSIONS_DIR, sweptSessions).catch(() => {});
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
removeHandoffs(sweptHandoffs).catch(() => {});
};
// A standing instruction the new agent is owed, as `subagents` and a
@@ -1107,7 +1117,8 @@ function consume(dir, resultPath, result, url, chat = []) {
const [withWs, changes] = withWorkspace(dir, withChat);
const [out, subCursor] = withSubagents(dir, withWs);
const hop = hopFor(path.basename(dir), result);
print({ ...out, ...hop, ...(url ? { terminalLine: terminalLine(url) } : {}) });
markPickedUp(result);
print({ ...out, ...hop, ...handoffFor(result), ...(url ? { terminalLine: terminalLine(url) } : {}) });
try {
writeJsonAtomic(resultPath, collected);
} catch {}
@@ -1166,21 +1177,78 @@ const HOP_ACTIONS = {
launch: (a) => ({ workflow: a.workflow, spec: a.spec, skill: a.skill }),
dashboard: () => ({ workflow: "dashboard", skill: "plan2code" }),
commit: () => ({ workflow: "git", skill: "plan2code-git" }),
pickup: pickupHop,
};
// A pick-up hops into the skill and spec the handoff's `.json` names (the page
// sends only the id). When the skill is no longer installed, the spec folder
// is gone, or the Handoff skill wrote it, Quick Task picks it up instead,
// flagged so the agent says so. In a
// source tree no skill sits beside the console, so nothing can be told to be
// missing and the stored skill stands.
function skillPath(skill) {
return path.resolve(HERE, "..", "..", "..", skill, "SKILL.md");
}
function pickupHop(action) {
const id = action.handoff;
const meta = isHandoffId(id) ? readHandoffMeta(id) : null;
const handoffFile = isHandoffId(id) ? path.join(handoffsDir(), id + ".md") : undefined;
const quick = { workflow: "quick-task", spec: undefined, skill: "plan2code-quick-task", handoffFile, fallback: true };
if (!meta) return quick;
if (typeof meta.workflow !== "string" || !/^[a-z-]+$/.test(meta.workflow)) return quick;
// The Handoff skill's own handoff: resuming it would only write another one.
if (meta.workflow === "handoff") return quick;
if (typeof meta.skill !== "string" || !/^[a-z0-9-]+$/.test(meta.skill)) return quick;
const specGone =
typeof meta.spec === "string" && meta.spec && (!SAFE_SPEC.test(meta.spec) || !fs.existsSync(path.join(meta.worktree || "", meta.spec)));
const skillGone = !fs.existsSync(skillPath(meta.skill)) && fs.existsSync(skillPath("plan2code-quick-task"));
if (specGone || skillGone) return quick;
return { workflow: meta.workflow, spec: meta.spec || undefined, skill: meta.skill, handoffFile };
}
// A stop that asked for a handoff gets the Handoff skill's file beside it, so
// the agent opens it instead of locating it. Only a built skill has one.
function handoffFor(result) {
const actions = (result && Array.isArray(result.actions) && result.actions) || [];
if (!actions.some((a) => a && a.type === "stop" && a.i === "__stop" && a.handoff === true)) return {};
const file = path.resolve(HERE, "..", "..", "..", "plan2code-handoff", "SKILL.md");
return fs.existsSync(file) ? { handoffSkill: file } : {};
}
// A pick-up uses its handoff up as its hop is printed, so the next dashboard
// scan no longer lists it. Never fatal; a repeat delivery marks it again.
function markPickedUp(result) {
const actions = (result && Array.isArray(result.actions) && result.actions) || [];
for (const a of actions) {
if (a && a.type === "pickup" && typeof a.i === "string" && a.i.startsWith("__") && isHandoffId(a.handoff)) {
try {
markHandoffUsed(a.handoff);
} catch {}
}
}
}
// A spec name that is safe to put in the `resume` command: `specs/<name>` with
// nothing a shell would act on. A handoff's `.json` and a page's send are both
// data off disk or the wire, so the name is checked here and not trusted.
const SAFE_SPEC = /^specs\/[^/\\"'`$;&|<>(){}*?!#~\r\n]+$/;
function hopFor(sid, result) {
const actions = (result && Array.isArray(result.actions) && result.actions) || [];
const action = actions.find((a) => a && Object.hasOwn(HOP_ACTIONS, a.type) && typeof a.i === "string" && a.i.startsWith("__"));
if (!action) return {};
const { workflow, spec, skill } = HOP_ACTIONS[action.type](action);
const { workflow, spec, skill, handoffFile, fallback } = HOP_ACTIONS[action.type](action);
if (typeof workflow !== "string" || !/^[a-z-]+$/.test(workflow)) return {};
const quote = (v) => (/[\s"]/.test(v) ? `"${v.replace(/"/g, '\\"')}"` : v);
const specArg = typeof spec === "string" && spec ? ` --spec ${quote(spec)}` : "";
const specArg = typeof spec === "string" && SAFE_SPEC.test(spec) ? ` --spec ${quote(spec)}` : "";
const out = { resume: `node "${path.join(HERE, "console.mjs")}" open --resume ${sid} --no-open --workflow ${workflow}${specArg}` };
if (typeof skill === "string" && /^[a-z0-9-]+$/.test(skill)) {
const file = path.resolve(HERE, "..", "..", "..", skill, "SKILL.md");
const file = skillPath(skill);
if (fs.existsSync(file)) out.skillFile = file;
}
if (typeof handoffFile === "string") out.handoffFile = handoffFile;
if (fallback) out.fallback = true;
return out;
}
@@ -1323,6 +1391,47 @@ function cmdDeleteSpec() {
}
}
/* --------------------------------------------------------------- handoff */
// A handoff the agent is about to write, claimed in ~/.plan2code/handoffs/
// (handoffs.mjs) for this checkout: the Stop flow's "Stop with a handoff" and
// the Handoff skill both start here. Only the .json is written; the agent
// writes the document at the printed path.
function cmdHandoff() {
const usage = "handoff needs: handoff new --workflow <w> --skill <s> [--spec specs/<x>] [--title <t>] [--from-stop]";
if (args._[0] !== "new" || args._.length > 1) die(usage, 2);
if (typeof args.workflow !== "string" || typeof args.skill !== "string") die(usage, 2);
if ("from-stop" in args && args["from-stop"] !== true) die("--from-stop takes no value", 2);
const { worktree, project } = repoRoots();
try {
const { id, path: file, meta } = newHandoff({
worktree,
project,
spec: args.spec,
workflow: args.workflow,
skill: args.skill,
title: args.title,
fromStop: args["from-stop"] === true,
});
print({ ok: true, id, path: file, meta });
} catch (err) {
print({ ok: false, message: err.message });
process.exit(3);
}
}
// The dashboard's Delete on a Handoff chip, carried out by the agent, the
// same shape as delete-spec: removeHandoff() does every check.
function cmdDeleteHandoff() {
if (typeof args.handoff !== "string" || !args.handoff.trim()) die("delete-handoff needs --handoff <id>", 2);
try {
print(removeHandoff(args.handoff));
} catch (err) {
print({ ok: false, message: err.message });
process.exit(3);
}
}
/* ----------------------------------------------------------------- help */
function cmdHelp() {
@@ -1334,8 +1443,8 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
open [--file <payload.json>] [--workflow <w>] [--title "<t>"] [--spec <dir>]
[--session|--resume <sid>] [--no-open] [--idle-ms <ms>]
Start or resume a session and its server. Prints { ok, sid, session,
url, terminalLine }, plus swept { sessions, scratch } when old
sessions or scratch files were removed. Run it FIRST, before
url, terminalLine }, plus swept { sessions, scratch, handoffs } when
old sessions, scratch files or handoffs were removed. Run it FIRST, before
reading anything: the page shows a starting screen until your
first post. --file is optional, and --title defaults to the
project's folder name. Also prints workspace: { folders: [{ name,
@@ -1398,6 +1507,17 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
worktree: never a link, never deeper, never specs--completed/.
Prints { ok, removed }; exit 2 = bad usage, 3 = refused, with
{ ok: false, message } saying why. Nothing is touched on a refusal.
handoff new --workflow <w> --skill <s> [--spec specs/<name>] [--title "<t>"] [--from-stop]
Claim a handoff for this checkout in ~/.plan2code/handoffs/ (Stop
with a handoff, the Handoff skill). Writes only <id>.json; you write
the document at path. Prints { ok, id, path, meta }; exit 2 = bad
usage, 3 = a bad value, with { ok: false, message } saying why.
delete-handoff --handoff <id>
Delete that handoff for good (a Handoff chip's Delete, a __delete
action): <id>.md and <id>.json, only in ~/.plan2code/handoffs/,
never a link. Prints { ok, removed }; exit 2 = bad usage, 3 =
refused, with { ok: false, message } saying why. Nothing is touched
on a refusal.
status [--session <sid>] [--all]
One session, or (--all) every session on this machine, every project.
stop --session <sid> | --all
@@ -1665,6 +1785,8 @@ const COMMANDS = {
keep: cmdKeep,
forget: cmdForget,
"delete-spec": cmdDeleteSpec,
handoff: cmdHandoff,
"delete-handoff": cmdDeleteHandoff,
status: cmdStatus,
stop: cmdStop,
help: cmdHelp,
@@ -1684,7 +1806,7 @@ if (Number.isFinite(nodeMajor) && nodeMajor < 18) {
if (!cmd || !Object.hasOwn(COMMANDS, cmd)) {
process.stderr.write(
"console: usage: console.mjs <open|post|wait|chat|keep|forget|delete-spec|status|stop|help> [--session <id>] [--file <patch.json>] [--seconds N]\n"
"console: usage: console.mjs <open|post|wait|chat|keep|forget|delete-spec|handoff|delete-handoff|status|stop|help> [--session <id>] [--file <patch.json>] [--seconds N]\n"
);
process.exit(2);
}
@@ -1692,7 +1814,7 @@ if (!cmd || !Object.hasOwn(COMMANDS, cmd)) {
// A flag given with no value parses as `true`, and a boolean handed on as a
// path or a name crashes somewhere deep (path.basename(true) throws). Every
// flag that takes a value is checked once, here, and refused as bad usage.
const VALUE_FLAGS = ["session", "sid", "resume", "file", "spec", "title", "workflow", "upload", "name", "from", "seconds", "limit", "idle-ms"];
const VALUE_FLAGS = ["session", "sid", "resume", "file", "spec", "title", "workflow", "skill", "handoff", "upload", "name", "from", "seconds", "limit", "idle-ms"];
for (const flag of VALUE_FLAGS) {
if (flag in args && typeof args[flag] !== "string") die(`--${flag} needs a value`, 2);
}
+296
View File
@@ -0,0 +1,296 @@
// Plan2Code Web Console - the handoff store.
//
// Every handoff lives in one folder, outside every repo:
//
// ~/.plan2code/handoffs/<id>.md the Handoff skill's document, written by
// the agent and never changed here
// ~/.plan2code/handoffs/<id>.json who wrote it, for which checkout, spec
// and skill, and whether it was picked up
//
// This module is the only code that names, lists, marks, deletes and sweeps
// them. The console ships inside every skill, so the Stop flow, the Handoff
// skill and the dashboard all reach it through console.mjs commands.
// PLAN2CODE_HANDOFFS_DIR moves the folder, for tests.
//
// Node built-ins only. No build step.
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
export const HANDOFFS_DIR = process.env.PLAN2CODE_HANDOFFS_DIR || path.join(os.homedir(), ".plan2code", "handoffs");
// Read at call time, so a test that sets the variable after import sees it.
export function handoffsDir() {
return process.env.PLAN2CODE_HANDOFFS_DIR || path.join(os.homedir(), ".plan2code", "handoffs");
}
export const HANDOFF_ID = /^\d{4}-\d{2}-\d{2}-\d{4}-handoff(-\d+)?$/;
export function isHandoffId(id) {
return typeof id === "string" && HANDOFF_ID.test(id) && id === path.basename(id);
}
// PLAN2CODE_NOW ("YYYY-MM-DD HH:mm" or any Date-parsable string) pins the
// clock, as the skill scripts' now() does. Copied, not imported: the console
// is copied into skills on its own and may not reach src/skill-scripts/.
function clock() {
const pinned = process.env.PLAN2CODE_NOW;
if (pinned) {
const m = pinned.match(/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/);
if (m) return new Date(+m[1], +m[2] - 1, +m[3], +(m[4] || 0), +(m[5] || 0), +(m[6] || 0));
const d = new Date(pinned);
if (!Number.isNaN(d.getTime())) return d;
}
return new Date();
}
const pad = (n) => String(n).padStart(2, "0");
/* ----------------------------------------------------------------- write */
/**
* Claim a new handoff for the agent to write. The id is the local minute,
* `YYYY-MM-DD-HHmm-handoff`, with `-2`, `-3` and so on after a clash; the
* `.json` is created exclusively, so two sessions in the same minute never
* share one. Only the `.json` is written: the agent writes the `.md` at the
* returned path. A bad field throws, naming it, before anything is created.
*/
export function newHandoff({ worktree, project, spec, workflow, skill, title, fromStop } = {}, now = clock()) {
if (typeof workflow !== "string" || !/^[a-z-]+$/.test(workflow)) throw new Error(`workflow must be lowercase letters and dashes, got ${JSON.stringify(workflow)}`);
if (typeof skill !== "string" || !/^[a-z0-9-]+$/.test(skill)) throw new Error(`skill must be a skill name, got ${JSON.stringify(skill)}`);
if (spec !== undefined && spec !== null && spec !== "" && (typeof spec !== "string" || !/^specs\/[^/\\]+$/.test(spec))) {
throw new Error(`spec must be specs/<name>, got ${JSON.stringify(spec)}`);
}
const dir = handoffsDir();
fs.mkdirSync(dir, { recursive: true });
const base = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}-handoff`;
for (let n = 1; ; n++) {
const id = n === 1 ? base : `${base}-${n}`;
// A lone .md left by hand also holds its name.
if (fs.existsSync(path.join(dir, id + ".md"))) continue;
let fd;
try {
fd = fs.openSync(path.join(dir, id + ".json"), "wx");
} catch (err) {
if (err.code === "EEXIST") continue;
throw err;
}
const meta = {
v: 1,
id,
title: typeof title === "string" ? title : "",
worktree,
project,
spec: spec || null,
workflow,
skill,
written: now.toISOString(),
fromStop: Boolean(fromStop),
usedAt: null,
};
try {
fs.writeSync(fd, JSON.stringify(meta, null, 2) + "\n");
} finally {
fs.closeSync(fd);
}
return { id, path: path.join(dir, id + ".md"), meta };
}
}
/* ------------------------------------------------------------------ read */
// A regular file in the folder, never a link: lstat, not stat.
function regularFile(file) {
try {
return fs.lstatSync(file).isFile();
} catch {
return false;
}
}
/** The handoff's `.json`, or null: an invalid id, a missing or linked file, or not a v1 record. */
export function readHandoffMeta(id) {
if (!isHandoffId(id)) return null;
const file = path.join(handoffsDir(), id + ".json");
if (!regularFile(file)) return null;
try {
const meta = JSON.parse(fs.readFileSync(file, "utf8"));
return meta && typeof meta === "object" && meta.v === 1 ? meta : null;
} catch {
return null;
}
}
/** Stamp `usedAt` (a pick-up) and rewrite the `.json`; the `.md` is never touched. */
export function markHandoffUsed(id, now = clock()) {
const meta = readHandoffMeta(id);
if (!meta) return null;
const next = { ...meta, usedAt: now.toISOString() };
const file = path.join(handoffsDir(), id + ".json");
const tmp = `${file}.${process.pid}.tmp`;
fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
fs.renameSync(tmp, file);
return next;
}
const NEXT_MAX = 280;
// The case-folded resolved path, as removeSpec() compares realpaths.
function samePath(a, b) {
const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p);
return typeof a === "string" && typeof b === "string" && fold(path.resolve(a)) === fold(path.resolve(b));
}
// The document's first `# ` heading, without a leading "Handoff" and the
// punctuation after it.
function docTitle(md) {
const m = md.match(/^# (.+)$/m);
if (!m) return "";
return m[1].replace(/^Handoff\b/i, "").replace(/^[\s:\-\u2013\u2014]+/, "").trim();
}
// The first paragraph under `## Next task`, on one line and cut to NEXT_MAX.
function docNext(md) {
const lines = md.split(/\r?\n/);
const at = lines.findIndex((l) => /^##\s+Next task\b/i.test(l));
if (at < 0) return "";
const para = [];
for (const line of lines.slice(at + 1)) {
if (/^#{1,6}\s/.test(line)) break;
if (!line.trim()) {
if (para.length) break;
continue;
}
para.push(line.trim());
}
const text = para.join(" ").replace(/\s+/g, " ").trim();
return text.length > NEXT_MAX ? text.slice(0, NEXT_MAX - 1).trimEnd() + "…" : text;
}
/**
* This checkout's handoffs still waiting to be picked up: a readable `.json`
* with no `usedAt`, a `.md` beside it, and the same worktree. Newest first,
* as `[{ id, title, next, written, spec, skill, workflow }]`.
*/
export function listHandoffs(worktree) {
const dir = handoffsDir();
let names;
try {
names = fs.readdirSync(dir);
} catch {
return [];
}
const out = [];
for (const name of names) {
if (!name.endsWith(".json")) continue;
const id = name.slice(0, -".json".length);
const meta = readHandoffMeta(id);
if (!meta || meta.usedAt || !samePath(meta.worktree, worktree)) continue;
const md = path.join(dir, id + ".md");
if (!regularFile(md)) continue;
let text;
try {
text = fs.readFileSync(md, "utf8");
} catch {
continue;
}
out.push({
id,
title: docTitle(text) || meta.title || "",
next: docNext(text),
written: meta.written,
spec: meta.spec ?? null,
skill: meta.skill,
workflow: meta.workflow,
});
}
return out.sort((a, b) => String(b.written).localeCompare(String(a.written)));
}
/* ---------------------------------------------------------------- remove */
/**
* Delete one handoff, both files (or whichever one exists), for the
* dashboard's Delete (`delete-handoff`). Only a handoff id; each file must be
* a regular file, never a link, whose real folder is the handoffs folder.
* Every refusal throws with the reason, and nothing is touched.
*/
export function removeHandoff(id) {
if (!isHandoffId(id)) throw new Error(`not a handoff id: ${id}`);
const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p);
const dir = handoffsDir();
const names = [id + ".md", id + ".json"];
const present = [];
for (const name of names) {
let st;
try {
st = fs.lstatSync(path.join(dir, name));
} catch {
continue;
}
if (st.isSymbolicLink()) throw new Error(`${name} is a link, so it is not deleted from here`);
if (!st.isFile()) throw new Error(`${name} is not a file`);
present.push(name);
}
if (!present.length) throw new Error(`there is no handoff ${id}`);
const realDir = fold(fs.realpathSync.native(dir));
for (const name of present) {
if (fold(path.dirname(fs.realpathSync.native(path.join(dir, name)))) !== realDir) {
throw new Error(`${name} resolves outside the handoffs folder, so it is not deleted`);
}
}
for (const name of present) fs.rmSync(path.join(dir, name));
return { ok: true, removed: present };
}
/* ----------------------------------------------------------------- sweep */
/**
* Handoffs untouched for `maxAgeMs`, picked up or not: the `.json`'s mtime,
* or the `.md`'s when there is no `.json`. Regular files with a handoff id
* only, as staleScratch() does for the console folder.
*/
export function staleHandoffs(now, maxAgeMs) {
const dir = handoffsDir();
let names;
try {
names = fs.readdirSync(dir);
} catch {
return [];
}
const ids = new Set();
for (const name of names) {
const m = name.match(/^(.+)\.(md|json)$/);
if (m && isHandoffId(m[1])) ids.add(m[1]);
}
const stale = [];
for (const id of ids) {
for (const ext of [".json", ".md"]) {
let st;
try {
st = fs.lstatSync(path.join(dir, id + ext));
} catch {
continue;
}
if (st.isFile() && now - st.mtimeMs > maxAgeMs) stale.push(id);
break;
}
}
return stale;
}
// Every id re-checked against the same rule before anything is removed.
export async function removeHandoffs(ids) {
const dir = handoffsDir();
const removed = [];
for (const id of ids) {
if (!isHandoffId(id)) continue;
try {
await fs.promises.rm(path.join(dir, id + ".md"), { force: true });
await fs.promises.rm(path.join(dir, id + ".json"), { force: true });
removed.push(id);
} catch {}
}
return removed;
}
+3 -2
View File
@@ -580,9 +580,10 @@ export async function removeScratch(consoleDir, names) {
// protected files, its sessions dir (old sessions go one by one, by age) and,
// under PLAN2CODE_CONSOLE_HOME, its runtime dir; ~/.plan2code keeps the
// console, the launcher (bin/, launcher.json), the install record that
// `plan2code update` reads (install.json) and the models the person added.
// `plan2code update` reads (install.json), the models the person added and
// the handoffs (old ones go one by one, by age, on open: handoffs.mjs).
const KEPT_CONSOLE_ENTRIES = new Set([...PROTECTED_CONSOLE_FILES, "sessions", "runtime"]);
export const KEPT_PLAN2CODE_ENTRIES = new Set(["console", "bin", "launcher.json", "install.json", "models.json"]);
export const KEPT_PLAN2CODE_ENTRIES = new Set(["console", "bin", "launcher.json", "install.json", "models.json", "handoffs"]);
// A stray must sit untouched this long before Cleanup lists it. The same
// folders hold files that live for milliseconds -- a held
// `workspaces.json.lock`, a `<file>.<pid>.tmp` between its write and its
+1 -1
View File
@@ -4,7 +4,7 @@ Workflow notes for `handoff`, part of the web console contract (`console.md`).
One gate: the next-task confirmation, then the document itself as a doc —
that is what the person is there to download. Give it no `saved` and paste it
as `md`: the handoff file often sits outside the project (the OS temp folder),
as `md`: the handoff file lives in `~/.plan2code/handoffs/`, outside the project,
where a `file` block is refused, and the download is the point. The finish carries no
`command`: the doc download is the point, and the dashboard button and the
"All done" line cover what comes next. Unless it is a pause, the finish carries
+1 -1
View File
@@ -67,8 +67,8 @@ only ever be offered once nothing could come of it:
"body": "Phase 3 is built. Read the report, try the checks, then approve it, review the code first, see it running, or say what to change.",
"verdicts": [
{ "id": "review", "label": "Review the code first" },
{ "id": "show", "label": "Show me it working" },
{ "id": "approve", "label": "Approve this phase" },
{ "id": "show", "label": "Show me it working" },
{ "id": "changes", "label": "I want changes" }
],
"token": { "approve": "approved", "changes": "needs changes", "show": "show me" },
+50 -2
View File
@@ -371,6 +371,16 @@ export function handoffShape(fin) {
// sentence: nothing Pathfinder would read as asking for a brief.
export const STOP_REPLY = "Stop here and save my place, so I can pick this up later.";
// The same request, with a handoff note written first. Same plain voice: the
// reply is read by the agent, and a word like "brief" would send Pathfinder
// off to write one.
export const STOP_HANDOFF_REPLY = "Stop here, save my place and write a handoff, so the dashboard can pick this up later.";
/** The `__stop` action; `handoff: true` only when the handoff choice was pressed. */
export function stopAction({ handoff } = {}) {
return handoff ? { i: "__stop", type: "stop", handoff: true } : { i: "__stop", type: "stop" };
}
/**
* Why a session-level button (Stop session, Back to the dashboard) cannot be
* pressed right now, or null when it can. Both wait for the person's turn:
@@ -813,7 +823,7 @@ const ON = { on: true };
export const GIT_INIT_NOTE = "Not a git repository yet: it offers to start one";
export const pendingNote = (n) => `${n} file${n === 1 ? "" : "s"} to commit`;
const off = (reason) => ({ on: false, reason });
const FIXED_REASON = "This bug is fixed. Delete it with ✕, or move it to specs--completed/.";
export const FIXED_REASON = "This bug is fixed. Delete it with the Delete button on its chip, or move it to specs--completed/.";
/**
* The spec the picker opens on: the most recently touched one that is still
@@ -955,12 +965,50 @@ export function deleteReply(spec) {
// What the delete dialog says about the spec, from the scan alone. `touched`
// stays a number: the page formats it in the person's own locale.
// A handoff on the dashboard (scan.handoffs). The page sends only the id; the
// CLI reads the rest from the stored metadata. Plain wording, no em dashes:
// these lines are read by the agent.
export function pickupAction(h) {
return { i: "__pickup", type: "pickup", handoff: h.id };
}
export function pickupReply(h) {
return `Pick up the handoff "${h.title}" right here in this session.`;
}
export function deleteHandoffAction(h) {
return { i: "__delete", type: "delete", handoff: h.id };
}
export function deleteHandoffReply(h) {
return `Delete the handoff "${h.title}" for good, right here in this session.`;
}
export function handoffCopyText(file) {
return `Read the handoff at ${file} and carry on with its Next task.`;
}
/** "just now", "12 min ago", "6 h ago", "3 days ago" for an ISO time. */
export function handoffAge(written, now = Date.now()) {
const t = Date.parse(written);
if (!Number.isFinite(t)) return "";
const mins = Math.max(0, Math.floor((now - t) / 60000));
if (mins < 1) return "just now";
if (mins < 60) return `${mins} min ago`;
const hours = Math.floor(mins / 60);
if (hours < 24) return `${hours} h ago`;
const days = Math.floor(hours / 24);
return `${days} day${days === 1 ? "" : "s"} ago`;
}
// The line under a spec's name on its chip. A fixed bug's label already says
// "Bug fixed", so the scan's "bug fixed" detail would only repeat it.
export function chipDetail(spec) {
return spec.state === "fixed" ? "" : spec.detail || "";
}
export function deleteSummary(spec) {
const label = SPEC_STATE_LABELS[spec.state] || spec.state || "";
const detail = chipDetail(spec);
const n = spec.files;
return {
folder: `${spec.dir}/`,
stage: spec.detail ? `${label}: ${spec.detail}` : label,
stage: detail ? `${label}: ${detail}` : label,
files: Number.isInteger(n) ? `${n} file${n === 1 ? "" : "s"}` : "",
touched: Number.isFinite(spec.touched) && spec.touched > 0 ? spec.touched : null,
};
+98
View File
@@ -1761,6 +1761,9 @@ input[type="text"].invalid { border-color: var(--warn); }
.btn:disabled { opacity: 0.45; cursor: not-allowed; }
.btn.primary { background: var(--accent); border-color: var(--accent); color: var(--accent-ink); }
.btn.primary:hover:not(:disabled) { filter: brightness(1.08); background: var(--accent); }
/* A review card's approve verdict, before it is picked: the accent outline
marks it as the main way forward. */
.btn.is-approve { border-color: var(--accent); }
/* Send glows and breathes while there is something to send: the steady
--glow, plus a soft accent ring that spreads and fades. The ring is off
under reduced motion, below; the glow stays. */
@@ -2773,6 +2776,47 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
.modal-why { margin: 14px 0 0; font-size: 13px; color: var(--warn); min-height: 1px; }
.modal-actions { display: flex; justify-content: flex-end; gap: 10px; margin-top: 20px; }
/* The Stop dialog's two ways out, stacked: the handoff first (the suggested
one), the plain stop second, "Keep going" alone below. */
.stop-choices { display: grid; gap: 10px; margin-top: 16px; }
.stop-choice {
display: flex;
align-items: flex-start;
gap: 12px;
width: 100%;
padding: 12px 14px;
text-align: left;
font: inherit;
color: var(--ink);
background: var(--panel-2);
border: 1px solid var(--rule-2);
border-radius: var(--radius);
cursor: pointer;
}
.stop-choice:hover, .stop-choice.suggested { border-color: var(--accent); }
.stop-choice:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
.stop-choice:disabled { opacity: 0.6; cursor: default; }
.stop-choice[hidden] { display: none; }
.stop-choice-icon {
flex: none;
display: inline-flex;
align-items: center;
justify-content: center;
width: 28px;
height: 28px;
border-radius: 50%;
border: 1px solid var(--rule-2);
font-size: 13px;
color: var(--accent);
}
.stop-choice-text { display: grid; gap: 2px; min-width: 0; }
.stop-choice-title { font-weight: 600; font-size: 14px; }
.stop-choice-detail { font-size: 12.5px; color: var(--ink-2); }
.modal-actions:has(#stop-cancel) { justify-content: center; margin-top: 14px; }
@media (max-width: 560px) {
.modal-actions:has(#stop-cancel) .btn { width: 100%; }
}
/* ----------------------------------------------------------- doc tools */
.doc-tools { display: flex; gap: 8px; margin-left: auto; flex: none; align-items: center; }
@@ -3056,6 +3100,38 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
}
.spec-chip:not(.is-sel) .spec-chip-state { color: var(--ink-3); }
.spec-chip-detail { font-size: 11.5px; color: var(--ink-3); }
/* A handoff in the picker: the same lozenge, dashed, in the stage colour. */
.spec-chip.is-handoff { border-style: dashed; }
.spec-chip.is-handoff .spec-chip-state, .spec-chip.is-handoff:not(.is-sel) .spec-chip-state { color: var(--stage); }
.spec-chip.is-handoff.is-sel { border-style: solid; border-color: var(--stage); }
.spec-chip.is-handoff.is-deleting { opacity: 0.5; }
/* What a picked handoff shows under the picker. */
.handoff-preview {
margin: 0 0 30px;
padding: 18px 20px;
background: var(--panel);
border: 1px solid var(--stage);
border-radius: var(--radius);
}
.handoff-preview-title { font: 600 20px/1.25 var(--serif); margin: 0 0 4px; }
.handoff-preview-meta { margin: 0 0 14px; font-size: 12.5px; color: var(--ink-3); }
.handoff-preview-label {
margin: 0 0 3px;
font-size: 10.5px;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
color: var(--stage);
}
.handoff-preview-next { margin: 0 0 16px; font-size: 14px; color: var(--ink); }
.handoff-preview-actions { display: flex; flex-wrap: wrap; gap: 10px; }
.handoff-preview-actions .btn.danger { margin-left: auto; }
.modal.handoff-read { max-width: 720px; }
.modal.handoff-read[open] { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
.handoff-body { flex: 1; min-height: 0; overflow-y: auto; margin-top: 8px; }
.modal.handoff-read .modal-actions { flex: none; }
/* A spec's Delete button sits beside its chip, not inside it: a button cannot
hold a button. Quiet until the chip is hovered or focused. */
.spec-chip-wrap { position: relative; display: flex; }
@@ -3085,6 +3161,28 @@ a.icon-btn { box-sizing: border-box; text-decoration: none; }
.spec-chip-del:hover { color: var(--warn); border-color: var(--warn); opacity: 1; }
.spec-chip-del:focus-visible { outline: 2px solid var(--warn); outline-offset: 1px; }
.spec-chip-del:disabled { cursor: default; opacity: 0.3; }
/* A fixed bug's Delete is always shown, as a pill at the chip's bottom right;
the chip makes room below its lines so the pill never covers the name. The
chip's is-fixed dimming targets .spec-chip, so the pill keeps full strength. */
.spec-chip-wrap.is-fixed .spec-chip { padding-right: 14px; padding-bottom: 36px; }
.spec-chip-del-label {
position: absolute;
right: 8px;
bottom: 8px;
padding: 2px 10px;
border: 1px solid var(--warn);
border-radius: 999px;
background: var(--panel);
color: var(--warn);
font: inherit;
font-size: 12.5px;
font-weight: 600;
line-height: 1.5;
cursor: pointer;
}
.spec-chip-del-label:hover:not(:disabled) { background: var(--warn-soft); }
.spec-chip-del-label:focus-visible { outline: 2px solid var(--warn); outline-offset: 1px; }
.spec-chip-del-label:disabled { cursor: default; opacity: 0.4; }
.spec-chip-wrap.is-deleting .spec-chip { opacity: 0.5; }
.delete-facts { display: grid; grid-template-columns: auto 1fr; gap: 6px 14px; margin: 14px 0 0; font-size: 13.5px; }
.delete-facts dt { color: var(--ink-3); }
+300 -32
View File
@@ -9,7 +9,7 @@
// that is local and reversible. For someone who has never used a tool like
// this, that reversibility is the whole point.
import { md, el, copyButton, selectContents } from "./render.js";
import { md, mdInto, el, copyButton, selectContents } from "./render.js";
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, SOUND_EVENTS, cardWidth, soundKey, soundPrefs } from "./palette.js";
import { activityLabel, workingLine } from "./labels.js";
import { playWake } from "./boot.js";
@@ -46,6 +46,13 @@ import {
launchTarget,
deleteAction,
deleteReply,
pickupAction,
pickupReply,
deleteHandoffAction,
deleteHandoffReply,
handoffCopyText,
handoffAge,
chipDetail,
deleteSummary,
isDeletableSpecDir,
MAX_ATTACHMENTS,
@@ -71,6 +78,8 @@ import {
STALE_MS,
startPose,
STOP_REPLY,
STOP_HANDOFF_REPLY,
stopAction,
sentAnswer,
agentRepliedAfterSend,
indentReply,
@@ -831,6 +840,22 @@ const selSpec = () => {
return specs.find((s) => s.dir === local.specSel) || null;
};
// This checkout's unused handoffs (scan.handoffs, newest first). A handoff is
// picked in the same chip row as a spec, stored as `specSel = "handoff:<id>"`;
// selSpec() then reads as "no spec", and selHandoff() is the handoff itself,
// or null once it is gone from the scan (which also drops the stale pick).
const handoffList = () => {
const sc = scan();
return sc && Array.isArray(sc.handoffs) ? sc.handoffs : [];
};
const selHandoff = () => {
if (typeof local.specSel !== "string" || !local.specSel.startsWith("handoff:")) return null;
const id = local.specSel.slice("handoff:".length);
const h = handoffList().find((x) => x.id === id) || null;
if (!h) delete local.specSel;
return h;
};
// The review a finished build offers, and where it has got to:
// "open" on offer, and a press would reach the agent
// "asked" pressed, and the agent has not taken it up yet
@@ -3098,6 +3123,10 @@ function openUpdateModal() {
function renderDashboard(main) {
maybeWake();
// First, so nothing below reads a pick whose handoff has left the scan, and
// a delete the agent's rescan has finished stops holding the buttons.
selHandoff();
settleDeleting();
const menu = (S && S.menu) || {};
const wrap = el("div", "dash");
if (needsRoleNudge(looks)) wrap.appendChild(roleNudge());
@@ -3159,7 +3188,17 @@ function renderDashboard(main) {
}
const specs = specList();
if (specs.length) wrap.appendChild(renderSpecPicker(specs));
if (specs.length || handoffList().length) wrap.appendChild(renderSpecPicker(specs));
const handoff = selHandoff();
if (handoff) {
// A handoff is picked up, not launched: its skill and spec come from its
// own record, so the skill cards and their toggle have nothing to say.
if (!local.launching && !launchScoping && scopeMine !== "") syncWorkspaceScope();
wrap.appendChild(renderHandoffPreview(handoff));
main.appendChild(wrap);
queueMicrotask(maybeWelcome);
return;
}
wrap.appendChild(hideUnavailableToggle());
// Only when this tab's own pick moved: another tab changing the scope
// sends a frame here too, and re-asserting this tab's pick on every render
@@ -3678,13 +3717,18 @@ function hideUnavailableToggle() {
no send — so it costs nothing to change your mind. */
function renderSpecPicker(specs) {
const sel = selSpec();
const handoffs = handoffList();
const pickedHandoff = selHandoff();
const box = el("section", "spec-pick");
box.appendChild(el("h3", "dash-group-title", "Pick up a spec, or start fresh"));
box.appendChild(
el("h3", "dash-group-title", handoffs.length ? "Pick up a spec or a handoff, or start fresh" : "Pick up a spec, or start fresh")
);
const row = el("div", "spec-row");
const scratch = el("button", "spec-chip" + (sel ? "" : " is-sel"));
const scratchOn = !sel && !pickedHandoff;
const scratch = el("button", "spec-chip" + (scratchOn ? " is-sel" : ""));
scratch.type = "button";
scratch.setAttribute("aria-current", String(!sel));
scratch.setAttribute("aria-current", String(scratchOn));
scratch.appendChild(el("span", "spec-chip-name", "Start from scratch"));
scratch.appendChild(el("span", "spec-chip-state", "a new idea"));
scratch.addEventListener("click", () => {
@@ -3695,13 +3739,6 @@ function renderSpecPicker(specs) {
});
row.appendChild(scratch);
// A delete in flight ends when the agent's rescan lands (a new scan), gone
// or refused: either way the picker below is the truth again.
const sc = scan();
if (local.deleting && sc && sc.at !== local.deleting.scanAt) {
local.deleting = null;
save();
}
for (const spec of specs) {
const on = sel && sel.dir === spec.dir;
// A fixed bug is finished: hidden while unavailable workflows are, dimmed
@@ -3715,7 +3752,8 @@ function renderSpecPicker(specs) {
b.setAttribute("aria-current", String(Boolean(on)));
b.appendChild(el("span", "spec-chip-name", spec.name));
b.appendChild(el("span", "spec-chip-state", deleting ? "Deleting…" : SPEC_STATE_LABELS[spec.state] || spec.state));
if (spec.detail) b.appendChild(el("span", "spec-chip-detail", spec.detail));
const detail = chipDetail(spec);
if (detail) b.appendChild(el("span", "spec-chip-detail", detail));
b.addEventListener("click", () => {
local.specSel = spec.dir;
save();
@@ -3724,7 +3762,9 @@ function renderSpecPicker(specs) {
});
wrap.appendChild(b);
if (isDeletableSpecDir(spec.dir)) {
const del = el("button", "spec-chip-del", "✕");
// A fixed bug is done with, so its Delete is a visible button rather
// than the hover ✕ every other spec has.
const del = fixed ? el("button", "spec-chip-del-label", "Delete") : el("button", "spec-chip-del", "✕");
del.type = "button";
del.title = `Delete ${spec.dir}/`;
del.setAttribute("aria-label", `Delete the spec ${spec.name}`);
@@ -3734,10 +3774,139 @@ function renderSpecPicker(specs) {
}
row.appendChild(wrap);
}
// Handoffs follow the specs: dashed chips, the state word is "Handoff".
for (const h of handoffs) {
const on = Boolean(pickedHandoff && pickedHandoff.id === h.id);
const deleting = Boolean(local.deleting && local.deleting.dir === "handoff:" + h.id);
const b = el("button", "spec-chip is-handoff" + (on ? " is-sel" : "") + (deleting ? " is-deleting" : ""));
b.type = "button";
b.setAttribute("aria-current", String(on));
b.appendChild(el("span", "spec-chip-name", h.title || "Handoff"));
b.appendChild(el("span", "spec-chip-state", deleting ? "Deleting…" : "Handoff"));
b.appendChild(el("span", "spec-chip-detail", handoffAge(h.written)));
b.addEventListener("click", () => {
local.specSel = "handoff:" + h.id;
save();
render();
});
row.appendChild(b);
}
box.appendChild(row);
return box;
}
// A delete in flight ends when the agent's rescan lands (a new scan), gone
// or refused: either way the picker is the truth again.
function settleDeleting() {
const sc = scan();
if (local.deleting && sc && sc.at !== local.deleting.scanAt) {
local.deleting = null;
save();
}
}
// What a picked handoff shows: where it came from and its Next task, with the
// four things to do with it.
function renderHandoffPreview(h) {
const box = el("section", "handoff-preview");
box.appendChild(el("h3", "handoff-preview-title", h.title || "Handoff"));
const entry = SKILL_CATALOG.find((e) => e.skill === h.skill);
const meta = [
"Written " + (h.written ? new Date(h.written).toLocaleString() : "at an unknown time"),
h.spec ? "spec " + h.spec.replace(/^specs\//, "") : "no spec",
"from " + (entry ? entry.title : h.skill),
];
box.appendChild(el("p", "handoff-preview-meta", meta.join(" · ")));
if (h.next) {
box.appendChild(el("p", "handoff-preview-label", "Next task"));
box.appendChild(el("p", "handoff-preview-next", h.next));
}
const busy = Boolean(local.launching || local.deleting) || gone || pendingResult;
const actions = el("div", "handoff-preview-actions");
const go = el("button", "btn primary", "Pick it up here");
go.type = "button";
go.disabled = busy;
go.addEventListener("click", () => pickUpHandoff(h));
const read = el("button", "btn", "Read it all");
read.type = "button";
read.addEventListener("click", () => readHandoff(h));
const copy = el("button", "btn", "Copy for a new conversation");
copy.type = "button";
copy.addEventListener("click", () => {
const dir = (scan() && scan().handoffsDir) || "";
const sep = dir.includes("\\") ? "\\" : "/";
const file = dir ? dir.replace(/[\\/]+$/, "") + sep + h.id + ".md" : h.id + ".md";
copyHandoffText(handoffCopyText(file), copy);
});
const del = el("button", "btn danger", "Delete");
del.type = "button";
del.disabled = busy;
del.addEventListener("click", () => openHandoffDelete(h));
actions.append(go, read, copy, del);
box.appendChild(actions);
return box;
}
// The prompt that sends a new conversation to the handoff. A refused
// clipboard gets a plain word on the button instead of a silent nothing.
async function copyHandoffText(text, button) {
try {
await navigator.clipboard.writeText(text);
button.textContent = "Copied";
} catch {
button.textContent = "Copy was refused";
}
setTimeout(() => (button.textContent = "Copy for a new conversation"), 1500);
}
// Pick it up here: a hop like a card launch. The page sends only the id; the
// CLI reads the stored skill and spec, marks the handoff used and falls back
// to Quick Task if either is gone.
async function pickUpHandoff(h) {
if (gone || pendingResult || local.launching || finish()) return;
launchScoping = true;
await syncWorkspaceScope(h.spec || "");
try {
const res = await fetch("/submit", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ actions: [pickupAction(h)], reply: pickupReply(h) }),
});
if (res.status === 409) {
launchScoping = false;
pendingResult = true;
banner("Your last pick is still being picked up. One moment.", "info");
return;
}
if (!res.ok) throw new Error(String(res.status));
sound("startSkill");
local.launching = { skill: h.skill, title: h.title || "the handoff", at: Date.now() };
launchScoping = false;
pendingResult = true;
save();
render();
} catch {
launchScoping = false;
banner("That did not go through. Nothing was lost; try again.", "warn");
}
}
// Read it all: the document, in a dialog, from /handoff?id= (served only for
// an id the dashboard's own scan listed).
async function readHandoff(h) {
$("handoff-title").textContent = h.title || "Handoff";
const body = $("handoff-body");
body.replaceChildren(el("p", "md-p", "Reading…"));
$("handoff-modal").showModal();
try {
const res = await fetch("/handoff?id=" + encodeURIComponent(h.id), { cache: "no-store" });
if (res.status !== 200) throw new Error(String(res.status));
mdInto(body, await res.text());
} catch {
body.replaceChildren(el("p", "md-p", "This handoff could not be read."));
}
}
function dashCard(entry, menu) {
const presentation = cardPresentation(entry, scan(), selSpec(), menu);
// The agent's `recommend` and detail describe the initially selected spec.
@@ -5248,8 +5417,13 @@ function buildReview(card, item, staged) {
for (const v of verdicts) {
const on = staged && staged.verdict === v.id;
// A picked danger verdict stays red (filled), so choosing "Abort" never
// reads like choosing the safe default.
const b = el("button", "btn" + (on ? (v.danger ? " danger is-on" : " primary") : v.danger ? " danger" : ""), verdictText(v));
// reads like choosing the safe default. An unpicked approve is outlined
// in the accent, so the main way forward stands out.
const b = el(
"button",
"btn" + (on ? (v.danger ? " danger is-on" : " primary") : v.danger ? " danger" : v.id === "approve" ? " is-approve" : ""),
verdictText(v)
);
b.type = "button";
b.addEventListener("click", () =>
stage(item.id, withNote(item, on ? null : { type: "answer", kind: "review", verdict: v.id }))
@@ -7550,13 +7724,58 @@ function openHomeConfirm() {
// The picker's Delete: a dialog in two steps. The first says what goes and
// that it is for good; "Delete this spec…" then reveals the second, which
// enables the final button only once the spec's name is typed exactly.
// enables the final button only once the spec's name is typed exactly. A
// fixed bug skips the second step: its first press sends the delete.
// Cancel, Escape or a click on Keep it at either step changes nothing.
let deleteTarget = null;
// The spec warning as index.html writes it, kept so a fixed bug's wording
// never sticks for the next spec.
let deleteWarnDefault = null;
// A handoff's Delete reuses the same dialog in one step: no name to type, and
// the warning says where the file lives instead of what git does not track.
function openHandoffDelete(h) {
if (gone || pendingResult || local.launching || local.deleting) return;
deleteTarget = { handoff: h };
$("delete-title").textContent = "Delete this handoff?";
$("delete-blurb").textContent = "This handoff will be deleted from ~/.plan2code/handoffs/.";
$("delete-warn").hidden = true;
$("delete-warn-handoff").hidden = false;
const facts = $("delete-facts");
facts.replaceChildren();
const fact = (term, value) => {
if (!value) return;
facts.appendChild(el("dt", "", term));
facts.appendChild(el("dd", "", value));
};
const entry = SKILL_CATALOG.find((e) => e.skill === h.skill);
fact("Handoff", h.title || h.id);
fact("Written", h.written ? new Date(h.written).toLocaleString() : "");
fact("Spec", h.spec ? h.spec.replace(/^specs\//, "") : "");
fact("From", entry ? entry.title : h.skill);
$("delete-confirm").hidden = true;
const go = $("delete-go");
go.textContent = "Delete it";
go.classList.add("is-on");
go.disabled = false;
$("delete-modal").showModal();
}
function openDeleteConfirm(spec) {
if (!isDeletableSpecDir(spec.dir) || gone || pendingResult || local.launching || local.deleting) return;
deleteTarget = spec;
// A fixed bug is finished work: one confirm, and a warning that says so.
const fixed = spec.state === "fixed";
$("delete-title").textContent = "Delete this spec?";
const warn = $("delete-warn");
if (!deleteWarnDefault) deleteWarnDefault = [...warn.childNodes].map((n) => n.cloneNode(true));
warn.replaceChildren(
...(fixed
? ["The bug is fixed, so this only clears the write-up. ", el("code", "", "specs/"), " is not tracked by git, so it cannot be brought back."]
: deleteWarnDefault.map((n) => n.cloneNode(true)))
);
warn.hidden = false;
$("delete-warn-handoff").hidden = true;
const sum = deleteSummary(spec);
$("delete-blurb").textContent = `Everything in ${sum.folder} will be deleted from this project.`;
const facts = $("delete-facts");
@@ -7575,8 +7794,8 @@ function openDeleteConfirm(spec) {
$("delete-name").value = "";
$("delete-confirm").hidden = true;
const go = $("delete-go");
go.textContent = "Delete this spec…";
go.classList.remove("is-on");
go.textContent = fixed ? "Delete it" : "Delete this spec…";
go.classList.toggle("is-on", fixed);
go.disabled = false;
$("delete-modal").showModal();
}
@@ -7584,6 +7803,8 @@ function openDeleteConfirm(spec) {
function deleteStep() {
const go = $("delete-go");
if (!deleteTarget) return;
if (deleteTarget.handoff) return sendDeleteHandoff(deleteTarget.handoff);
if (deleteTarget.state === "fixed") return sendDelete(deleteTarget);
if ($("delete-confirm").hidden) {
$("delete-confirm").hidden = false;
go.textContent = "Delete for good";
@@ -7596,6 +7817,38 @@ function deleteStep() {
sendDelete(deleteTarget);
}
async function sendDeleteHandoff(h) {
const go = $("delete-go");
go.disabled = true;
try {
const res = await fetch("/submit", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ actions: [deleteHandoffAction(h)], reply: deleteHandoffReply(h) }),
});
if (res.status === 409) throw Object.assign(new Error("pending"), { pending: true });
if (!res.ok) throw new Error(String(res.status));
const sc = scan();
local.deleting = { dir: "handoff:" + h.id, scanAt: sc ? sc.at : null };
if (local.specSel === "handoff:" + h.id) delete local.specSel;
pendingResult = true;
save();
$("delete-modal").close();
} catch (err) {
$("delete-modal").close();
if (err && err.pending) pendingResult = true;
banner(
err && err.pending
? "Your last pick is still being picked up, so that could not go yet. Nothing was deleted; try again in a moment."
: "That did not go through. Nothing was deleted; try again.",
"warn"
);
} finally {
deleteTarget = null;
render();
}
}
async function sendDelete(spec) {
const go = $("delete-go");
go.disabled = true;
@@ -7684,29 +7937,42 @@ function openStopConfirm() {
}
const n = Object.keys(local.staged).length + pendingNotes().length;
const warn = stopWarning();
const dash = isDashboard();
$("stop-blurb").textContent =
(n === 1 ? "The answer you have ready goes with it. " : n ? `The ${n} answers you have ready go with it. ` : "") +
(isDashboard()
? "Nothing has started yet, so there is nothing to save: this just ends the console session."
: warn
? "Plan2Code stops here."
: "Plan2Code will save your place and give you a command to pick this up later, in a new conversation.");
(dash ? "Nothing has started yet, so there is nothing to save: this just ends the console session." : "");
$("stop-blurb").hidden = !$("stop-blurb").textContent;
$("stop-warn").hidden = !warn;
$("stop-warn").textContent = warn;
$("stop-go").textContent = isDashboard() ? "Stop" : warn ? "Stop anyway" : "Stop and save";
// The dashboard has nothing to hand off: one plain Stop. Elsewhere both
// choices show, and "Just stop and save" turns into "Stop anyway" where
// nothing is saved yet.
$("stop-handoff").hidden = dash;
const title = $("stop-go").querySelector(".stop-choice-title");
const detail = $("stop-go").querySelector(".stop-choice-detail");
if (dash) {
title.textContent = "Stop";
detail.textContent = "Ends the console session.";
} else if (warn) {
title.textContent = "Stop anyway";
detail.textContent = "Ends the session now. What the warning above names is not kept.";
} else {
title.textContent = "Just stop and save";
detail.textContent = "Saves what this step keeps on disk and gives you a command to resume. What we talked about is not kept.";
}
$("stop-modal").showModal();
}
async function stopSession() {
const go = $("stop-go");
go.disabled = true;
async function stopSession(handoff = false) {
const buttons = [$("stop-handoff"), $("stop-go")];
for (const b of buttons) b.disabled = true;
const payload = stagedPayload();
payload.actions.push({ i: "__stop", type: "stop" });
payload.actions.push(stopAction({ handoff }));
try {
const res = await fetch("/submit", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ actions: payload.actions, reply: [...payload.replyLines, STOP_REPLY].join("\n") }),
body: JSON.stringify({ actions: payload.actions, reply: [...payload.replyLines, handoff ? STOP_HANDOFF_REPLY : STOP_REPLY].join("\n") }),
});
if (res.status === 409) throw Object.assign(new Error("pending"), { pending: true });
if (!res.ok) throw new Error(String(res.status));
@@ -7725,7 +7991,7 @@ async function stopSession() {
"warn"
);
} finally {
go.disabled = false;
for (const b of buttons) b.disabled = false;
render();
}
}
@@ -8299,6 +8565,7 @@ function openHelpOn(id) {
$("btn-home").addEventListener("click", openHomeConfirm);
$("update-done").addEventListener("click", () => $("update-modal").close());
$("delete-cancel").addEventListener("click", () => $("delete-modal").close());
$("handoff-close").addEventListener("click", () => $("handoff-modal").close());
$("delete-go").addEventListener("click", deleteStep);
$("delete-name").addEventListener("input", () => {
$("delete-go").disabled = !deleteTarget || $("delete-name").value.trim() !== deleteTarget.name;
@@ -8316,7 +8583,8 @@ $("home-cancel").addEventListener("click", () => $("home-modal").close());
$("home-go").addEventListener("click", goHome);
$("btn-stop").addEventListener("click", openStopConfirm);
$("stop-cancel").addEventListener("click", () => $("stop-modal").close());
$("stop-go").addEventListener("click", stopSession);
$("stop-handoff").addEventListener("click", () => stopSession(true));
$("stop-go").addEventListener("click", () => stopSession(false));
$("stopping-hide").addEventListener("click", () => {
stoppingHidden = true;
$("stopping-modal").close();
+70 -7
View File
@@ -1661,6 +1661,23 @@
<strong>Hide unavailable workflows</strong>, under the picker, hides
them instead. It is on to begin with, and remembered on this machine.
</p>
<p>
The <strong>✕</strong> on a spec deletes its folder, after two steps:
one says what goes, the other wants the spec's name typed. A fixed
bug has its own <strong>Delete</strong> button at the bottom of its
chip instead, and needs just one confirm, since the work is done.
</p>
<p>
A <strong>Handoff</strong> is a note a step left when you stopped it
with a handoff. It shows as a dashed chip after the specs. Pick one
and the cards give way to a preview with its Next task and four
buttons: <strong>Pick it up here</strong> carries on in the same step
and spec, <strong>Read it all</strong> shows the whole note,
<strong>Copy for a new conversation</strong> puts a ready prompt on
the clipboard, and <strong>Delete</strong> removes it. A picked-up
handoff drops off the list, but stays in
<code>~/.plan2code/handoffs/</code> until the 30-day sweep.
</p>
<h4>The Suggested flag</h4>
<p>
One card may carry a <strong>Suggested</strong> flag: where Plan2Code
@@ -2092,8 +2109,16 @@
through writing your answers down.
</li>
<li>
It asks first. <strong>Keep going</strong> backs out;
<strong>Stop and save</strong> stops.
It asks first, and offers two ways to stop.
<strong>Stop with a handoff</strong> saves your place and writes a
note the dashboard can offer to pick up later;
<strong>Just stop and save</strong> saves what the step keeps on
disk and gives you a command to resume, without the conversation;
<strong>Keep going</strong> backs out.
</li>
<li>
A handoff lands in <code>~/.plan2code/handoffs/</code> and shows on
the dashboard, next to your specs, until you use or delete it.
</li>
<li>
At points where nothing is saved yet, such as early in a plan, the
@@ -2245,7 +2270,9 @@
that folder is usually gitignored and git can't restore it. It
shows each one with its size, and <strong>Delete these</strong>
removes exactly that list. Your preferences, saved folders, models,
the launcher and the session you are in always stay.
the launcher and the session you are in always stay, and the
<code>handoffs/</code> folder is Plan2Code's own, so it is never
offered for removal.
</li>
<li>
<strong>Back to default</strong> puts everything back as it was, and
@@ -2296,7 +2323,10 @@
this machine who has it can open the session.
</p>
<h4>What is kept, and where</h4>
<p>Everything lives under <code>~/.plan2code/console/</code> in your home folder:</p>
<p>
Everything lives in your home folder, under
<code>~/.plan2code/console/</code> unless noted:
</p>
<ul>
<li>
each session's questions, your drafts and your answers, in
@@ -2314,7 +2344,13 @@
</li>
<li>
your Subagents switch for each project and skill, in
<code>subagents.json</code>.
<code>subagents.json</code>;
</li>
<li>
handoffs you save when you stop or with the Handoff skill, in
<code>~/.plan2code/handoffs/</code>, one <code>.md</code> and one
<code>.json</code> each, removed after the same
<span data-fact="cleanupDays">30</span> days.
</li>
</ul>
<p>
@@ -2585,20 +2621,37 @@
<!-- Only when stopping now would lose answers. A button that says it
saves has to be true about the times it cannot. -->
<p class="modal-why" id="stop-warn" hidden></p>
<div class="stop-choices">
<button type="button" class="stop-choice suggested" id="stop-handoff">
<span class="stop-choice-icon" aria-hidden="true">&#x270E;</span>
<span class="stop-choice-text">
<span class="stop-choice-title">Stop with a handoff</span>
<span class="stop-choice-detail">Saves your place and writes a handoff note. Next time the dashboard offers to pick it up right where this left off.</span>
</span>
</button>
<button type="button" class="stop-choice" id="stop-go">
<span class="stop-choice-icon" aria-hidden="true">&#x25A0;</span>
<span class="stop-choice-text">
<span class="stop-choice-title">Just stop and save</span>
<span class="stop-choice-detail">Saves what this step keeps on disk and gives you a command to resume. What we talked about is not kept.</span>
</span>
</button>
</div>
<div class="modal-actions">
<button type="button" class="btn ghost" id="stop-cancel">Keep going</button>
<button type="button" class="btn primary" id="stop-go">Stop and save</button>
</div>
</dialog>
<!-- Deleting a spec from the dashboard's picker. Two deliberate steps: the
first says what goes and that it is for good, the second wants the
spec's name typed. The page only asks; the agent deletes. -->
spec's name typed. A fixed bug takes the first step only. The page
only asks; the agent deletes. -->
<dialog class="modal" id="delete-modal" aria-labelledby="delete-title">
<h2 id="delete-title">Delete this spec?</h2>
<p class="modal-blurb" id="delete-blurb"></p>
<dl class="delete-facts" id="delete-facts"></dl>
<p class="modal-why" id="delete-warn">This is permanent. <code>specs/</code> is not tracked by git, so nothing can bring these files back.</p>
<p class="modal-why" id="delete-warn-handoff" hidden>Handoffs are not kept anywhere else.</p>
<div class="delete-confirm" id="delete-confirm" hidden>
<label for="delete-name">To delete it for good, type <strong id="delete-name-hint"></strong></label>
<input type="text" id="delete-name" autocomplete="off" spellcheck="false" />
@@ -2609,6 +2662,16 @@
</div>
</dialog>
<!-- A handoff's whole document, from the dashboard's "Read it all". Escape
closes it; the body is filled by the page with rendered markdown. -->
<dialog class="modal handoff-read" id="handoff-modal" aria-labelledby="handoff-title">
<h2 id="handoff-title">Handoff</h2>
<div class="handoff-body md" id="handoff-body"></div>
<div class="modal-actions">
<button type="button" class="btn ghost" id="handoff-close">Close</button>
</div>
</dialog>
<dialog class="modal" id="home-modal" aria-labelledby="home-title">
<h2 id="home-title">Leave this workflow?</h2>
<p class="modal-blurb" id="home-blurb"></p>
+16
View File
@@ -75,6 +75,7 @@ import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
import { checkForUpdate } from "./update-check.mjs";
import { handoffsDir, isHandoffId } from "./handoffs.mjs";
import { WORKSPACE_PICKER_PROMPT, pickFolder, pickerCommand } from "./picker.mjs";
const args = parseArgs(process.argv.slice(2));
@@ -1211,6 +1212,21 @@ const server = http.createServer((req, res) => {
return;
}
// A handoff's document, read-only, for the dashboard's "Read it all". Only a
// dashboard serves it, and only an id its own scan listed: a used or unknown
// id, or anything that is not a bare handoff id, is a 404.
if (pathname === "/handoff" && req.method === "GET") {
const state = readState() || {};
const id = url.searchParams.get("id");
const listed = state.workflow === "dashboard" && isHandoffId(id) && (state.scan?.handoffs || []).some((h) => h && h.id === id);
if (!listed) return send(res, 404, "", "text/plain");
fs.readFile(path.join(handoffsDir(), id + ".md"), "utf8", (err, text) => {
if (err) return send(res, 404, "", "text/plain");
send(res, 200, text, "text/markdown; charset=utf-8", { "cache-control": "no-store" });
});
return;
}
if (pathname === "/version" && req.method === "GET") {
const version = installedVersion();
if (version) return json(res, 200, { version, latest: updateLatest });