/new and /back are built-ins; the daemon forks a session with session.fork, its log the parent's after session_forked; troupe resume takes latest, --private and --headless "message"; what another device holds or what is erased is refused, saying why and offering /new¶
Decision 812 · accepted · 2026-10-08 · issue #484
- Two built-ins in the harness's table.
new(sectionsession,/new [--private | --remote PROFILE | --branch]) andback(sectionnavigate), sotroupe --help, the reference and both palettes list them (Decisions 698, 767). The desktop app greys them with its default reason; the TUI runs them (TUI Decision 151). A file in.troupe/commands/namednew.mdorback.mdis now shadowed by the built-in, as Decision 763 shadows every built-in's name. /new --branchis a fork, and the daemon has one now. The plane'ssession.forkcopies a parent's history into a new session on a pod; the daemon had none, and a "branch" in its sense (session.createwithparent, Decision 646) is a second agent in the parent's window, not the conversation carried on elsewhere.session.fork {session_id, config?}on the daemon answers{session_id, workspace, forked_from}. So the child's agent starts from the parent's conversation; the parent is neither changed nor woken.- A fork is not a branch. No
parentin its row: a branch is shown in its parent's window, and a fork is a session of its own, in the picker, with its own budget (a restart forgets the budget, State's own rule) and its own erasure. - Not a private session, yet. Its child would be a copy no plane knows of, sealed
nowhere, and erasing the parent would leave it.
invalid_paramswithreason: "private", and one being erased isnot_foundwith"erased", assession.claimsays it. A pod refusessession.forkas it refuses archive, pin and erase: it is the plane's (done through the plane), a new row, key and placement. troupe resumegrows, rather than a second command.latest: the newest session here, straight in;--private: the newest private one; neither: the picker, as before. "Newest" is not a branch, and is one that did something before an empty scratch session (which also mendstroupe resumeopening a branch or an empty session, a clause of D43 in defects.md, trimmed there). An id is that session wherever its directory.--headless "message"runs one turn and exits with the codestroupe run --headlessexits with. The session is named (an id,latest, or--privatealone), since there is no picker, and a lone word afterresumeis refused rather than guessed at. Its client name istroupe-headless(Decision 787).- What is refused, and what is not. Refused, in one sentence that says why and offers
/new, from the CLI and from the TUI's picker,/resumeand/backalike (Client.resume_refusal/1,open_refusal/2): a private session another device holds (sync: "elsewhere", Decision 785: carrying it on here would make two histories, so it says to claim it first); one erased, or being erased; an id the daemon does not have (not_found: erased locally, or never here; the daemon forgets an erased local session, so the two read alike). An archived session is not refused.session.archivemakes a session dormant, on the daemon and on the plane alike, and PROTOCOL.md says an activating command brings a dormant one back: refusing it would make archiving a door that only closes.resumeopens it, and the next line wakes it.
Governs: apps/troupe_protocol/lib/troupe/sessions/fork.ex, clients/tui/lib/troupe/cli.ex, clients/tui/lib/troupe/cli/runner.ex