fix(agents): unreadable lists start nothing, retitled sessions are found, agents:reset; claude-code additionalDirectories (agents 1.0.1, claude-code 1.8.0, devcontainer-cli 1.14.0)

TODO.md

@@ -277,9 +277,21 @@ stays. Ids are short descriptive slugs (two to four kebab-case words naming the
 - [x] **release-cloud-folder-1-1-0 Release cloud-folder 1.1.0 after the step 2 pull request merges** (the Operator). Step 2 (`sync` mode) ships as cloud-folder 1.1.0 once #83 is in; consumers cannot pull it until the release runs. The host does not start the release. Added 2026-10-27. Done 2026-10-27.
 - [ ] **cloud-folder-sync-live-check Check cloud-folder sync on a real sign-in** (the Operator). After the 1.1.0 release: one real sign-in, a file each way between the container and the SharePoint folder, and a stop in the middle of a sync, to see what the sync does when it is interrupted. Added 2026-10-27.
 - [ ] **agents-lexicon-terms Land the agent-model terms on the agents branch** (host). The librarian's three terms (resident agent, on-demand agent, agent list) were taken out of the step 2 commit: they came ahead of the Operator's decision and their ontology entries are missing, so the guard would refuse them. The saved patch in the session scratchpad goes onto the agents branch with those entries. Added 2026-10-27.
-- [ ] **agents-commit Commit and open the pull request for the agents build** (the Operator). The `agents` 1.0.0 Feature, the Claude adapter (claude-code 1.7.0), the host task (devcontainer-cli 1.13.0) and this repository's `.devcontainer/agents.yml` pass their unit tests and the repository checks in a worktree, but nothing is committed. The host commits and opens the pull request only on the Operator's word. Added 2026-10-27.
-- [ ] **agents-ci-check Read the first CI run of the agents tests** (engineers). The container tests of the `agents` Feature have not run with Docker anywhere but CI; read the first CI run and file what it shows. Added 2026-10-27.
-- [ ] **release-agents Release agents 1.0.0, claude-code 1.7.0 and devcontainer-cli 1.13.0 after the agents pull request merges** (the Operator). The host does not start the release. Once it runs, rebuild the devhost here so the launcher and `task agents` carry the change. Added 2026-10-27.
+- [x] **agents-commit Commit and open the pull request for the agents build** (the Operator). The `agents` 1.0.0 Feature, the Claude adapter (claude-code 1.7.0), the host task (devcontainer-cli 1.13.0) and this repository's `.devcontainer/agents.yml` pass their unit tests and the repository checks in a worktree, but nothing is committed. The host commits and opens the pull request only on the Operator's word. Added 2026-10-27. Done 2026-10-27.
+- [x] **agents-ci-check Read the first CI run of the agents tests** (engineers). The container tests of the `agents` Feature have not run with Docker anywhere but CI; read the first CI run and file what it shows. Added 2026-10-27. Done 2026-10-27.
+- [x] **release-agents Release agents 1.0.0, claude-code 1.7.0 and devcontainer-cli 1.13.0 after the agents pull request merges** (the Operator). The host does not start the release. Once it runs, rebuild the devhost here so the launcher and `task agents` carry the change. Added 2026-10-27. Done 2026-10-28.
+- [ ] **agents-migration-send Send the agents migration guide downstream** (the Operator). After the agents release runs, send `docs/migrations/agents.md` to agentic-operating-framework, so it can drop `join.sh` and use `task agents -- <name>`. Outward-facing, so the Operator sends it. Added 2026-10-27.
+- [ ] **agents-rebuild-check Check the agents after the devhost rebuild** (the Operator). The devhost was rebuilt on agents 1.0.0 and claude-code 1.7.0, and the result of the rebuild checks is not recorded here yet; on the workstation, check what comes back after the rebuild (the attached sessions and `task devcontainer:agent -- <name>`), and record whether the rebuilt devhost has the `agents` Feature. Added 2026-10-28.
+- [ ] **agents-list-on-demand-none agents:list shows "none" for an on-demand agent's old session** (host). After a rebuild `agents:list` showed yesterday's stopped session of an on-demand agent (`d7621154`, found by the name "host"). In agents 1.0.1 it shows only running sessions for on-demand agents, or "none". The host session is named only when started with `task devcontainer:agent -- host`. Added 2026-10-28.
+- [ ] **agents-session-state-read Check the agents Feature still reads session state after a Claude Code update** (host). An office launcher reported agents as "unknown" after Claude Code 2.1.312 and new sessions in place of resumed ones. The host found `--json` and `--all` still exist on 2.1.312; what `claude agents --json` prints there, and what the adapter reads, is not yet checked. Added 2026-10-28.
+- [ ] **agents-unreadable-list-fix Stop agents starting fresh when the session list is unreadable** (host). Ships as agents 1.0.1 and claude-code 1.7.1 from branch `fix/agents-session-state-read/1`: a failed list starts nothing (a resident agent refuses and prints how to resume; `--resume` on an on-demand agent opens Claude's picker), and the Claude adapter finds the JSON after a stray line, retries once with a longer timeout and says why it failed. Tests cover the case where the list cannot be read. The Operator starts the release. Added 2026-10-28.
+- [ ] **claude-additional-dirs A claude-code option for extra folders** (host). The office's `claude` wrapper adds `--add-dir ~/.claude-shared` to every command, and `--add-dir` swallowed `agents` (2026-10-28). Offer an option such as `additionalDirectories` that writes `permissions.additionalDirectories` into Claude's settings, so consumers can delete the wrapper. Until then they move `--add-dir` after the arguments or skip it for `agents`, `attach` and `logs`. Added 2026-10-28.
+- [ ] **agents-fix-release Review, merge and release agents 1.0.1 and claude-code 1.8.0** (the Operator). One pull request from `fix/agents-session-state-read/1` carries the unreadable-list fix and the `additionalDirectories` option (claude-code goes to 1.8.0; agents stays at 1.0.1). Nothing is committed yet; the host does not start the release. Added 2026-10-28.
+- [ ] **office-add-dir-wrapper Drop the office's `--add-dir` wrapper once claude-code 1.8.0 ships** (the Operator). Tell the office now to move `--add-dir` after the arguments, then, after the release and a rebuild, to delete the wrapper and set `permissions.additionalDirectories` instead. Added 2026-10-28.
+- [ ] **agents-retitle-check Check agents finds a session after Claude Code retitles it** (the Operator). The bug report from agentic-operating-framework: Claude Code renames a background session after its first real prompt, and `agents` then found the old names and started copies. On the workstation, after the release and a rebuild, send a first prompt to a resident agent and check that `agents:list` and `task devcontainer:agent -- <name>` still find the live session by its id. Added 2026-10-28.
+- [ ] **managed-settings-fallback Fallback for Claude settings pushed centrally** (host). The claude-code Feature writes its settings to the managed folder, which Claude Code ignores when an organisation pushes settings centrally (admin console or device management). Build the harder fallback (a merge into the user's `settings.json`, removed again when the option changes) only if the office's `/status` shows centrally pushed settings. Added 2026-10-28.
+- [ ] **agents-ci-85-check Read the checks on #85 after the retitle fix** (host). The first CI run on #85 failed; the retitle fix and `agents:reset` went in as 856227e, and the checks on that commit are not read yet. Read them and fix what fails before the release. Added 2026-10-28.
+- [ ] **agents-reset-real-check Try agents:reset on a real container** (host). `reset` and `reset --purge` have run only against stubs and the unit tests. After the release, run `task agents:reset -- --all` on the workstation: read the plan first, check the duplicates it names, and only then add `--yes`. Added 2026-10-28.
 
 ## Next
 
@@ -419,3 +431,4 @@ stays. Ids are short descriptive slugs (two to four kebab-case words naming the
 - [x] **cloud-folder-commit Commit, push and open the pull request for cloud-folder step 1** (the Operator). Step 1 (`host` mode), the proposal, ADR 0031 and the records are in the working tree, nothing committed; the host recommends one commit, with cloud-folder at 1.0.0 and devcontainer-cli at 1.12.0, once the Operator has checked the rework. Added 2026-10-27. Done 2026-10-27.
 - [x] **agent-kinds-two Two agent kinds or three?** (the Operator). The host's draft has three kinds (interface, general, contractor), each deciding what start means; the Operator suggested less prescription: two kinds, background (kept running, attached on start) and on-demand (resumed or started when asked), or the kind simply stated in `agents.yml`. No recommendation recorded. Added 2026-10-27. Done 2026-10-27: two kinds, `resident` and `on-demand` (`agent-kind-standard`).
 - [ ] **agents-file-decisions Where the agent list lives and what wins** (the Operator). Three decisions in the agents proposal (`docs/proposals/agents.md`): how a repository points at its agent list instead of the default `.devcontainer/agents.yml` (a Feature option or the `AGENTS_FILE` variable), that paths in it are relative to the repository root, and which one wins when both are set (the proposal recommends one). The five open session-pin items wait on this decision. Added 2026-10-27.
+- [ ] **reset-uncommitted-scope Scope of the uncommitted-changes check in agents:reset** (the Operator). Should the check that refuses a session with uncommitted changes unless `--force` apply only to `--purge`, or to every reset as built (ADR 0033)? As built, a reset of an agent with uncommitted work stops without `--force`; the host wants this answered before the release, so agentic-operating-framework's first `agents:reset -- --all` needs no `--force`. No recommendation given. Added 2026-10-28.

Taskfile.yml

@@ -104,18 +104,19 @@ tasks:
       - task: test:agent-task
 
   test:claude-unit:
-    desc: 'Docker-free tests of the claude-code Feature''s claude-host live-session rule (a running session, one with a pid, refuses a second copy; ended sessions never count; CLAUDE_HOST_ALLOW_SECOND; the stale-pin warning and CLAUDE_HOST_UPDATE_PIN; `claude agents --json` unavailable), of the claude-host-pin SessionStart hook (the right .env line, every other byte kept, never fails) of claude-fleet (running by id or by folder, unset variable, start with --bg in the folder, --plan, --no-view, the environment beating .env), the deprecation line of the three, and of agent-adapter-claude (list from `claude agents --json --all`, a session found by name and folder, every action by id, a stopped one woken with --bg --resume <session id>, never -c, never rm, resume refused while running, --extras); a fake claude on PATH answers `agents --json` and records the other calls; part of lint.'
+    desc: 'Docker-free tests of the claude-code Feature''s claude-host live-session rule (a running session, one with a pid, refuses a second copy; ended sessions never count; CLAUDE_HOST_ALLOW_SECOND; the stale-pin warning and CLAUDE_HOST_UPDATE_PIN; `claude agents --json` unavailable), of the claude-host-pin SessionStart hook (the right .env line, every other byte kept, never fails) of claude-fleet (running by id or by folder, unset variable, start with --bg in the folder, --plan, --no-view, the environment beating .env), the deprecation line of the three, and of agent-adapter-claude (list from `claude agents --json --all`, a session found by name and folder, every action by id, a stopped one woken with --bg --resume <session id>, never -c, never rm, resume refused while running, --extras; the list read past a notice line, a slow first read tried again, a quick error such as a wrapper''s said as it is and not retried, resume on an unreadable list opening Claude Code''s own picker, never a new session; the record of each agent''s session, so a retitled session is still found and never started twice, a /clear and a removed session resolved; session-stop, session-remove, record), and of the additionalDirectories managed-settings drop-in (empty, one, several, a space in a path, ~ expanded, re-run idempotent, a relative path refused); a fake claude on PATH answers `agents --json` and records the other calls; part of lint.'
     cmds:
       - bash test/claude-code/unit/live_session_test.sh
       - bash test/claude-code/unit/adapter_test.sh
+      - bash test/claude-code/unit/additional_dirs_test.sh
 
   test:agents-unit:
-    desc: 'Docker-free tests of the agents Feature''s agents command: the agent list (the YAML subset, required keys, unknown keys warned, errors with file and line), AGENTS_FILE from the task variable, .env, .devcontainer/.env, the environment or the default (a missing file named with its source), each verb per kind (start, --resume, --new and its question, up, list, stop, logs), the no-terminal rule, the fallbacks when the adapter answers exit 3, the once-per-container-start marker, and the Feature Taskfile; a fake adapter keeps sessions in a file and records every call; part of lint. Needs task for the Taskfile part.'
+    desc: 'Docker-free tests of the agents Feature''s agents command: the agent list (the YAML subset, required keys, unknown keys warned, errors with file and line), AGENTS_FILE from the task variable, .env, .devcontainer/.env, the environment or the default (a missing file named with its source), each verb per kind (start, --resume, --new and its question, up, list, stop, logs), the no-terminal rule, the fallbacks when the adapter answers exit 3, a listing that fails (state error, nothing started, the hint, never a fresh session), an on-demand agent shown none unless running, reset (a dry run by default, duplicates stopped, --purge, only listed agents and their folders, unlisted sessions untouched, a session mid-turn not stopped, uncommitted changes a warning and with --purge a refusal, --force, refused inside a Claude Code session, --all), the once-per-container-start marker, and the Feature Taskfile; a fake adapter keeps sessions in a file and records every call; part of lint. Needs task for the Taskfile part.'
     cmds:
       - bash test/agents/unit/agents_test.sh
 
   test:agent-task:
-    desc: 'Docker-free test of how `task devcontainer:agent` and `devcontainer:agent:list` hand the name, the flags and AGENTS_FILE to the agents command, inside the container and through the exec task from the host (--dry), and that the deprecated devcontainer:claude and devcontainer:claude:fleet still run and print one deprecation line; fake commands record what they get; part of lint.'
+    desc: 'Docker-free test of how `task devcontainer:agent`, `devcontainer:agent:list` and `devcontainer:agent:reset` hand the name, the flags and AGENTS_FILE to the agents command, inside the container and through the exec task from the host (--dry), and that the deprecated devcontainer:claude and devcontainer:claude:fleet still run and print one deprecation line; fake commands record what they get; part of lint.'
     cmds:
       - bash test/bootstrap/agent_task_test.sh
 

bootstrap/devcontainer.yml

@@ -80,7 +80,7 @@
 #                              ahead). No single quote in it. The contract is in
 #                              bootstrap/SHUTDOWN.md in the collection.
 #   FORCE=1 (task var)         stop/rebuild without running that check.
-#   AGENTS_FILE                for `agent` and `agent:list`: the agent list, relative to the
+#   AGENTS_FILE                for `agent`, `agent:list` and `agent:reset`: the agent list, relative to the
 #                              repository root (default .devcontainer/agents.yml; the agents
 #                              Feature resolves it inside: task variable, .env, environment).
 #   HOST_SESSION               (deprecated with `claude`) UUID of the Claude Code session that the claude
@@ -360,6 +360,14 @@ tasks:
         vars:
           CMD: '{{if .AGENTS_FILE}}AGENTS_FILE_TASK_VAR={{.AGENTS_FILE | shellQuote}} {{end}}agents list {{.CLI_ARGS}}'
 
+  agent:reset:
+    desc: 'Tidy the listed agents'' sessions inside the devcontainer (the agents Feature: task agents:reset), starting the container first: task devcontainer:agent:reset -- <name>... | --all [--purge] [--include-unlisted] [--yes] [--force]. A dry run that prints the plan unless --yes. Runs directly when already inside the container (refused from inside a Claude Code session).'
+    interactive: true
+    cmds:
+      - task: run
+        vars:
+          CMD: '{{if .AGENTS_FILE}}AGENTS_FILE_TASK_VAR={{.AGENTS_FILE | shellQuote}} {{end}}agents reset {{.CLI_ARGS}}'
+
   claude:
     desc: 'Deprecated: use task devcontainer:agent -- <name> (the agents Feature); goes with claude-code 2.0. Start or resume the Claude Code host session inside the devcontainer (claude-host from the claude-code Feature), starting the container first (through exec, which runs up; idempotent): the session named by HOST_SESSION in .devcontainer/.env is resumed by UUID, or created the first time; unset, a plain new session. DIR=<sub-folder> starts there and reads HOST_SESSION_<DIR> instead (e.g. DIR=rooms/solis -> HOST_SESSION_SOLIS); SESSION=<uuid> overrides both. Extra arguments after --: task devcontainer:claude -- --model sonnet. Runs directly when already inside the container.'
     interactive: true