sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Mouse-1 notes: measured behaviour, the cold start trap, and where it is worth using

Browse Source 
Cold call 503 after ~30s, retry 200 after ~13s, warm 489-1044ms, stable answers at ~0.98
confidence. Effective for failure routing, unblock triage, intake clarity and task sizing.
Never for merge decisions, judging tests, keystroke paths, vague options, or as the only
record. Not needed before Milestone 1.
This commit is contained in:
sam
2026-11-11 16:28:48 +11:00
parent e02b39943d
commit c50c1efa22
5 changed files with 362 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
.pi/memory-vault/packs/paperclip-harness/20-context/cleanup-now-asks-before-it-closes-anything-and-the-three-que.md Normal file
View File

@@ -0,0 +1,95 @@
---
type: context
id: context.paperclip-harness.cleanup-now-asks-before-it-closes-anything-and-the-three-que
title: cleanup-now-asks-before-it-closes-anything-and-the-three-que
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-11
tags:
- pack/paperclip-harness
- agent-memory/context
- autolearn
- rich-discovery
- repo/cleanup-now-asks-before-it-closes-anything-and-the-three-que
---
# cleanup-now-asks-before-it-closes-anything-and-the-three-que
## Rich discovery update (2026-11-11 04:58:08)
Cleanup now asks before it closes anything, and the three questions have proper answers.
## Cleanup: the confirmation was missing entirely
`x` set a flag that nothing drew, so it looked like a no-op — and if it had run, it would have closed things with no chance to stop it. There is now a dialog, and the list refreshes afterwards:
```
╭─ close 1 session? ───────────────────────────────────·focus· ╮
│ what happens these TUIOS sessions are closed and their p…│
│ nothing in ~/.pi/paperclips is deleted; tha…│
│ this project's session and attached session…│
│ y close them │
│ esc or n do nothing │
│ office-test-1-card-t1-build-skele… │
```
I tested it by closing one junk card session: the row disappeared and the list reloaded. `↑`/`↓` move, `▸` marks the cursor, `*` marks a tick.
## What `verify.sh` is
`.harness/verify.sh` is a script in the project folder whose only job is to answer *"is this project's work finished?"* — exit 0 means yes.
- It is **not** Paperclip's. Paperclip has no such idea; an agent sets a task's status.
- It is **ours**, from the old project, and `bin/office` now writes a template that says `no verify command agreed for this project` and exits 0. Replace the body with the real tests when there are any (`exec go test ./...`).
- `bin/merge` runs it in the task's worktree, and again on `main` after merging. A task can carry its own command in its description, which wins for that task.
A per-project default, a per-task override, both optional. If neither exists, merge says so and the `ocr` review decides.
## Headroom
You are right to question my line. Headroom is a **compression proxy** — long prompts get shortened before reaching the model. It is good where prompts are long and repetitive (big repos, long threads, many tool results) and pointless for a small task where it adds a hop and a failure mode. The lever is per **agent**, because the provider is configured on the agent: `adapterConfig.env` can point one agent at `192.168.20.13:8787` without touching the others. That is why I put a read-out in `Agents>settings` first: until one agent runs both ways and you compare cost and quality, "good for some projects" is a hypothesis, not a setting.
## Mouse-1 — I was wrong
It is a **hosted API**, not software. `MOUSE_API_KEY` is present; nothing needs installing; what is missing is a client call from our side. The old project's rule still holds: triage only, never a gate, never a permit — it could order `Board>needs`, never decide a merge. That correction is now in the docs.
## Switching projects — and your mental model is the right one
You are exactly right, and TUIOS has the verb for it:
```
tuios call switch-session '{"name":"office","host":"nixos-desktop"}'
```
A session lives on a **daemon**, and a daemon runs on one machine; where you sit is irrelevant. Today you sit at `.27` driving a session whose daemon is on `.13`. So "another machine" really means "another daemon".
`Project>project` → **projects** now lists every adopted project with session, machine and folder, and `enter` asks once and switches your client in place:
```
╭─ switch to paperclip-harness? ───────────────────────·focus· ╮
│ what happens your TUIOS client moves to that session │
│ session paperclip-harness │
│ machine nixos-desktop │
│ folder /tmp/pc-sandbox-2026-11-10 │
│ y switch │
```
A session on a daemon that is not in your client's `[hosts]` table is still listed, and the dialog tells you which machine it needs — that is the one case where you attach by hand.
Committed as `e02b399`. `docs/SESSIONS.md` explains sessions versus daemons, `docs/PLAN-INTERFACE.md` carries the three explanations above, and `docs/NEXT.md` is updated.
## Evidence
- Confidence: 84%
- Reason: Update component/repository context with detailed discovered structure and configuration
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-11 04:58:08 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-cleanup-now-asks-before-it-closes-anything-an|Rich discovery: cleanup-now-asks-before-it-closes-anything-and-the-three-que 2026-11-11 04:58:08]]
- context: [[packs/paperclip-harness/20-context/cleanup-now-asks-before-it-closes-anything-and-the-three-que|cleanup-now-asks-before-it-closes-anything-and-the-three-que]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|cleanup-now-asks-before-it-closes-anything-and-the-three-que repository structure and configuration patterns]]

79
.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md
View File

@@ -2817,3 +2817,82 @@ Everything else in `docs/NEXT.md` is now marked done. Committed as `36abdc1`; th
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-omni-2026-11-11-04-06-03|Rich discovery: omni 2026-11-11 04:06:03]]
- context: [[packs/paperclip-harness/20-context/omni|omni]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|omni repository structure and configuration patterns]]
---
## Update (2026-11-11 04:58:08)
## Structural/configuration observations (2026-11-11 04:58:08)
Cleanup now asks before it closes anything, and the three questions have proper answers.
## Cleanup: the confirmation was missing entirely
`x` set a flag that nothing drew, so it looked like a no-op — and if it had run, it would have closed things with no chance to stop it. There is now a dialog, and the list refreshes afterwards:
```
╭─ close 1 session? ───────────────────────────────────·focus· ╮
│ what happens these TUIOS sessions are closed and their p…│
│ nothing in ~/.pi/paperclips is deleted; tha…│
│ this project's session and attached session…│
│ y close them │
│ esc or n do nothing │
│ office-test-1-card-t1-build-skele… │
```
I tested it by closing one junk card session: the row disappeared and the list reloaded. `↑`/`↓` move, `▸` marks the cursor, `*` marks a tick.
## What `verify.sh` is
`.harness/verify.sh` is a script in the project folder whose only job is to answer *"is this project's work finished?"* — exit 0 means yes.
- It is **not** Paperclip's. Paperclip has no such idea; an agent sets a task's status.
- It is **ours**, from the old project, and `bin/office` now writes a template that says `no verify command agreed for this project` and exits 0. Replace the body with the real tests when there are any (`exec go test ./...`).
- `bin/merge` runs it in the task's worktree, and again on `main` after merging. A task can carry its own command in its description, which wins for that task.
A per-project default, a per-task override, both optional. If neither exists, merge says so and the `ocr` review decides.
## Headroom
You are right to question my line. Headroom is a **compression proxy** — long prompts get shortened before reaching the model. It is good where prompts are long and repetitive (big repos, long threads, many tool results) and pointless for a small task where it adds a hop and a failure mode. The lever is per **agent**, because the provider is configured on the agent: `adapterConfig.env` can point one agent at `192.168.20.13:8787` without touching the others. That is why I put a read-out in `Agents>settings` first: until one agent runs both ways and you compare cost and quality, "good for some projects" is a hypothesis, not a setting.
## Mouse-1 — I was wrong
It is a **hosted API**, not software. `MOUSE_API_KEY` is present; nothing needs installing; what is missing is a client call from our side. The old project's rule still holds: triage only, never a gate, never a permit — it could order `Board>needs`, never decide a merge. That correction is now in the docs.
## Switching projects — and your mental model is the right one
You are exactly right, and TUIOS has the verb for it:
```
tuios call switch-session '{"name":"office","host":"nixos-desktop"}'
```
A session lives on a **daemon**, and a daemon runs on one machine; where you sit is irrelevant. Today you sit at `.27` driving a session whose daemon is on `.13`. So "another machine" really means "another daemon".
`Project>project` → **projects** now lists every adopted project with session, machine and folder, and `enter` asks once and switches your client in place:
```
╭─ switch to paperclip-harness? ───────────────────────·focus· ╮
│ what happens your TUIOS client moves to that session │
│ session paperclip-harness │
│ machine nixos-desktop │
│ folder /tmp/pc-sandbox-2026-11-10 │
│ y switch │
```
A session on a daemon that is not in your client's `[hosts]` table is still listed, and the dialog tells you which machine it needs — that is the one case where you attach by hand.
Committed as `e02b399`. `docs/SESSIONS.md` explains sessions versus daemons, `docs/PLAN-INTERFACE.md` carries the three explanations above, and `docs/NEXT.md` is updated.
## Evidence
- Confidence: 82%
- Reason: Captured factual repo structure/configuration patterns from rich discovery
## Related learned memories <!-- same-turn-2026-11-11 04:58:08 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-cleanup-now-asks-before-it-closes-anything-an|Rich discovery: cleanup-now-asks-before-it-closes-anything-and-the-three-que 2026-11-11 04:58:08]]
- context: [[packs/paperclip-harness/20-context/cleanup-now-asks-before-it-closes-anything-and-the-three-que|cleanup-now-asks-before-it-closes-anything-and-the-three-que]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|cleanup-now-asks-before-it-closes-anything-and-the-three-que repository structure and configuration patterns]]

98
.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-cleanup-now-asks-before-it-closes-anything-an.md Normal file
View File

@@ -0,0 +1,98 @@
---
type: session
id: session.paperclip-harness.rich-discovery-cleanup-now-asks-before-it-closes-anything-an
title: Rich discovery: cleanup-now-asks-before-it-closes-anything-and-the-three-que 2026-11-11 04:58:08
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-11
tags:
- pack/paperclip-harness
- agent-memory/session
- autolearn
- rich-discovery
- repo/cleanup-now-asks-before-it-closes-anything-and-the-three-que
---
# Rich discovery: cleanup-now-asks-before-it-closes-anything-and-the-three-que 2026-11-11 04:58:08
Sanitized rich discovery snapshot captured automatically from the completed turn.
## Final answer snapshot
Cleanup now asks before it closes anything, and the three questions have proper answers.
## Cleanup: the confirmation was missing entirely
`x` set a flag that nothing drew, so it looked like a no-op — and if it had run, it would have closed things with no chance to stop it. There is now a dialog, and the list refreshes afterwards:
```
╭─ close 1 session? ───────────────────────────────────·focus· ╮
│ what happens these TUIOS sessions are closed and their p…│
│ nothing in ~/.pi/paperclips is deleted; tha…│
│ this project's session and attached session…│
│ y close them │
│ esc or n do nothing │
│ office-test-1-card-t1-build-skele… │
```
I tested it by closing one junk card session: the row disappeared and the list reloaded. `↑`/`↓` move, `▸` marks the cursor, `*` marks a tick.
## What `verify.sh` is
`.harness/verify.sh` is a script in the project folder whose only job is to answer *"is this project's work finished?"* — exit 0 means yes.
- It is **not** Paperclip's. Paperclip has no such idea; an agent sets a task's status.
- It is **ours**, from the old project, and `bin/office` now writes a template that says `no verify command agreed for this project` and exits 0. Replace the body with the real tests when there are any (`exec go test ./...`).
- `bin/merge` runs it in the task's worktree, and again on `main` after merging. A task can carry its own command in its description, which wins for that task.
A per-project default, a per-task override, both optional. If neither exists, merge says so and the `ocr` review decides.
## Headroom
You are right to question my line. Headroom is a **compression proxy** — long prompts get shortened before reaching the model. It is good where prompts are long and repetitive (big repos, long threads, many tool results) and pointless for a small task where it adds a hop and a failure mode. The lever is per **agent**, because the provider is configured on the agent: `adapterConfig.env` can point one agent at `192.168.20.13:8787` without touching the others. That is why I put a read-out in `Agents>settings` first: until one agent runs both ways and you compare cost and quality, "good for some projects" is a hypothesis, not a setting.
## Mouse-1 — I was wrong
It is a **hosted API**, not software. `MOUSE_API_KEY` is present; nothing needs installing; what is missing is a client call from our side. The old project's rule still holds: triage only, never a gate, never a permit — it could order `Board>needs`, never decide a merge. That correction is now in the docs.
## Switching projects — and your mental model is the right one
You are exactly right, and TUIOS has the verb for it:
```
tuios call switch-session '{"name":"office","host":"nixos-desktop"}'
```
A session lives on a **daemon**, and a daemon runs on one machine; where you sit is irrelevant. Today you sit at `.27` driving a session whose daemon is on `.13`. So "another machine" really means "another daemon".
`Project>project` → **projects** now lists every adopted project with session, machine and folder, and `enter` asks once and switches your client in place:
```
╭─ switch to paperclip-harness? ───────────────────────·focus· ╮
│ what happens your TUIOS client moves to that session │
│ session paperclip-harness │
│ machine nixos-desktop │
│ folder /tmp/pc-sandbox-2026-11-10 │
│ y switch │
```
A session on a daemon that is not in your client's `[hosts]` table is still listed, and the dialog tells you which machine it needs — that is the one case where you attach by hand.
Committed as `e02b399`. `docs/SESSIONS.md` explains sessions versus daemons, `docs/PLAN-INTERFACE.md` carries the three explanations above, and `docs/NEXT.md` is updated.
## Evidence
- Confidence: 86%
- Reason: Preserve full sanitized discovery detail from a rich investigation turn
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-11 04:58:08 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-cleanup-now-asks-before-it-closes-anything-an|Rich discovery: cleanup-now-asks-before-it-closes-anything-and-the-three-que 2026-11-11 04:58:08]]
- context: [[packs/paperclip-harness/20-context/cleanup-now-asks-before-it-closes-anything-and-the-three-que|cleanup-now-asks-before-it-closes-anything-and-the-three-que]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|cleanup-now-asks-before-it-closes-anything-and-the-three-que repository structure and configuration patterns]]

1
docs/DOCMAP.md
View File

@@ -13,6 +13,7 @@ it is a pointer and should be deleted or replaced.
| `CHECKLIST.md` | project root | the next session, step by step, with tick boxes |
| `docs/OPERATING-RULES.md` | this project | the nine rules: project folder, how work is judged, approvals, untrusted text, secrets, review and merge, one project per machine, cost, existing commands |
| `docs/TUIOS-RUNBOOK.md` | this project | how TUIOS works, the three machines, how to start a session, how to drive panes |
| `docs/MOUSE-1-NOTES.md` | this project | the decision model: how to call it, the cold start, and the four places it helps and the five it must not be used |
| `docs/PLAN.md` | this project | the plan: four screens, five milestones, who owns what |
| `docs/ENVIRONMENT-FACTS.md` | this project | ids, installed tools, the unproven heartbeat step |
| `docs/PAPERCLIP-API-NOTES.md` | this project | what we measured against the running Paperclip, with endpoints |

89
docs/MOUSE-1-NOTES.md Normal file
View File

@@ -0,0 +1,89 @@
# Mouse-1: what it is, how to call it, and where it actually helps
Written from measurements on this machine, 2026-11-08/09. Nothing here is guesswork; the
numbers are the ones we saw.
## What it is
A small decision model, called over HTTPS, that answers a **typed multiple-choice
question** about a **state you describe**. You do not ask it to write anything. You give it
up to a handful of options with a sentence defining each, and it returns the option it
thinks fits, with a confidence and a probability per option.
- Endpoint: `POST https://api.mouse.dev/v1/decisions`
- Auth: `Authorization: Bearer $MOUSE_API_KEY` (already in your environment)
- Body: `{"model":"mouse-1","state":{...},"questions":{"<id>":{"type":"choice","instructions":"...","criteria":{"<option>":"what this option means"}}}}`
- Response: `answers.<id>.{choice, confidence, probabilities}`
- It also offers `noul` and `score` modes. We have only used `decisions`.
About 100 ms is claimed. We measured differently (below), so plan for the measured numbers.
## The cold start, which is the only real trap
The model is idle until something calls it, and then takes minutes to be ready.
- **Cold:** first call returned `503 engine_timeout` after ~30 seconds of waiting. The body
says: "The model did not answer in time. After an idle period it takes a few minutes to
start; retry after the Retry-After header."
- **Retry once:** the second call returned `200` in ~13 seconds.
- **Warm:** 1044 ms on the first warm call, then ~489 ms steady.
- We saw this again today: `503 engine_timeout`, then `200` with `choice: "wire"`,
`confidence: 0.982`.
So the rule is: **retry once on 503, never block a person's keystroke on it, and never call
it on a path that has to be fast.** If it must be warm, call it once at the start of a run
and throw the answer away.
Determinism: the same state and options produced the same choice with confidence around
0.98 across calls. Treat it as a classifier, not a creative step.
## Where it is effective — the use cases we proved
**1. Failure routing.** A task failed. The useful question is not "fix it" but "what kind of
failure is this": redo the task, use a stronger model, fix the environment, or ask the
person. Options with one line each:
```json
{"model":"mouse-1",
"state":{"task":"build skeleton","test":"npm test","output":"...tail of the failure..."},
"questions":{"next":{"type":"choice",
"instructions":"This task failed. What does it need next?",
"criteria":{
"redo":"the work is incomplete or wrong; another attempt with the same agent is likely to succeed",
"stronger_model":"the task needs more capability than this model has",
"environment":"something outside the code is wrong: a missing tool, a service, a path",
"person":"a decision only the person can make"}}}}
```
This was built and measured in the old project (`bin/route-failure`): a cold call returned
503 after 30.5 s, the retry 200 after 12.8 s, and warm calls ranged 489–1044 ms with a
stable answer. It is the best use we found.
**2. Unblock triage.** A task is blocked and the thread has several messages: is it waiting
on the person, on another task, on a missing tool, or on a decision that was already made?
Same shape, four options, one paragraph of state.
**3. Intake clarity.** Before a goal becomes a plan: is this goal specific enough to plan,
or does it need one more question? That was designed and never built.
**4. Task sizing.** Given a task description, is it one task or does it need splitting?
Also designed, never built.
## Where it is not effective, and must not be used
- **Never as the merge decision.** Whether code is correct is decided by tests and review,
not by a model with no repository.
- **Never as a judge of test results.** If a test failed, it failed.
- **Never on a keystroke path.** The cold start alone rules it out.
- **Never with vague options.** "good" and "bad" give you nothing. Every option needs a
sentence that says what choosing it means.
- **Never as the only record.** Keep the answer, the confidence and the options with the
task, so a person can see why a machine decided something.
## How to use it in this project
Not at Milestone 1. Nothing in "one task, really run" needs it.
Add it when a task first fails for a reason that is not obvious, and use it only for
routing: which kind of failure is this, and therefore what should happen next. That is the
point where it saves a person's attention, which is the whole reason it is here.