stack/docs/plans/2026-10-11_managed-session-config.md

Managed session config: skills, model routing, unslop (2026-10-11)

Status: written by Sage, lead. It follows docs/plans/BRIEF-TEMPLATE.md. Jason ruled Q82, Q83 and Q84 option A, relayed by Mos. All three rows change what a managed session (the row 41 bundle, what mosaic talk starts) is given at launch, and all three touch packages/harness/src/bundle.mjs and the two adapters. They run one at a time in the order below, each after the one before it is done, so no two candidates edit the same files at once. Sage owns all three. The order is after rows 55, 42 and 49.

Two decisions shape the set. Q84 is its own row, not part of the skills row: the ms-unslop skill is guidance the model reads, and the hook is a check that runs on its output. They differ in files, failure mode and tests. Row 29 (console model switching) stays parked. It is a WebUI feature. When Jason reopens it, it reads the routing table this set adds.

Constraints that hold for all three rows:

• Fail closed. A launch that can't give a session what its role declares refuses, with a refusal code and a message naming the missing piece. Nothing is silently dropped or defaulted.
• --restricted stays on the Claude Code adapter, and no harness reads a default config location (~/.pi, ~/.claude) for skills, settings, extensions or hooks. Every file a session loads is in its bundle or named in its manifest with a digest.
• Run records stay write-once. Anything a session writes for later reading goes under its run directory.

Managed sessions get their role's skills on both harnesses

Problem

ROADMAP M17 says role contracts declare skill names and the runner passes them explicitly. Only the older path does it: scripts/agent.sh:173-184 reads a seat's skills, checks each is in <dataRoot>/skills-enabled and refuses if not. Managed sessions get none. packages/harness/src/bundle.mjs:147 writes skills: [], packages/harness/src/runner.mjs sets no MOSAIC_SKILLS, so adapters/pi/adapter.sh:52 runs Pi with --no-skills, and adapters/claude/adapter.sh passes --disable-slash-commands. Role files have no place for a skill list (packages/business/src/role.mjs:19). Today skills-enabled holds only ms-communications; ms-tools is installed but not enabled.

Owner and reviewer

• Owner: Sage.
• Reviewers: Darkwing and Filbert.

Files owned

• packages/business/src/role.mjs, packages/business/src/resolve.mjs and their tests
• roles/coder.json, roles/cto.json, roles/pm.json, roles/reviewer.json (the skills key only)
• packages/harness/src/bundle.mjs, packages/harness/src/runner.mjs, packages/harness/tests/, packages/harness/README.md
• packages/cli/src/launcher.mjs and its tests (the refusal only)
• adapters/pi/adapter.sh, adapters/claude/adapter.sh, adapters/README.md
• agents/sage/work/queue-<row>/

What ships

• Role files take an optional skills list: distinct names matching [A-Za-z0-9._-]+. A role without the key has no skills. The role version stays 2; the key is optional.

• Resolution carries the role's skill list. The bundle resolves each name against <dataRoot>/skills-enabled/<name>/SKILL.md. A name that isn't enabled refuses the launch with skill-not-enabled, naming the skill and scripts/skill.sh activate <name>.

• The bundle copies each resolved skill directory into the bundle, so a deactivate during the session doesn't change it. The manifest's skills lists each name, its bundle path and the sha256 of its SKILL.md.

• Pi gets the bundle copies through MOSAIC_SKILLS, which the adapter already turns into --skill flags. Claude Code gets the same skills and no others. Probe the way in first (a bundle-local plugin directory, or the skill text in the generated system prompt are the two candidates) with --restricted kept, and record the choice and its evidence in the packet and in adapters/README.md.

• First skill lists. ms-unslop is on every list because Jason requires it on all output. ms-tools is on none: it documents the conductor's repository scripts, which a managed session can't run.

  Role	Skills
  coder	ms-unslop, ms-sdlc, ms-file-read, ms-file-write
  reviewer	ms-unslop, ms-sdlc, ms-file-read
  cto	ms-unslop, ms-sdlc, ms-archify, ms-grill-me
  pm	ms-unslop, ms-goal, ms-communications

• Tests, each on both harnesses with the existing fake binaries: a session gets exactly its contracted skills (the argv or prompt the fake records lists those names and no others); a contracted skill that isn't enabled refuses the launch before any spawn; an enabled skill that isn't on the role's list is absent; a role with no list runs Pi with --no-skills and gives Claude Code none.

• Gate suites: node --test 'packages/business/tests/*.test.mjs', node --test 'packages/harness/tests/*.test.mjs', node --test 'packages/cli/tests/*.test.mjs', and every scripts/test-*.sh.

Out of scope

Per-instance or per-business skill lists (role files only for now). The mosaic skill CLI verbs (scripts/skill.sh stays the lifecycle tool). Enabling skills in the live data root: that is a landing step, below.

Gate

Darkwing and Filbert approve on the issue, naming the candidate manifest. The suites above pass on a gate rerun in a clean worktree. At landing, Sage installs and activates the skills the four lists name, then starts one managed coder session on each harness and attaches the manifest showing the four skills and their digests.

Model routing table: sessions resolve harness, model and thinking from one table

Problem

A session's harness, model and thinking come from free-string agent-layer vars (packages/business/src/vars.mjs:106-108) with the system's execution.adapter and execution.model as fallback (packages/harness/src/bundle.mjs:51-55). The launch cap guesses a model's family by substring (packages/seat/src/session.mjs:51, used at packages/cli/src/launcher.mjs:148), so a model name that contains neither opus nor sonnet, or both, refuses for the wrong reason, and a renamed model can move between families unnoticed. thinking is recorded in the manifest and applied to neither harness (packages/harness/README.md:188-190). The live business file mosaic-stack.json sets no harness, model or thinking for any role, and the system config has no execution.adapter, so a managed launch there refuses today with unsupported-harness. The row 41 recorded run used a test business with claude-code and claude-sonnet-5-5.

Owner and reviewer

• Owner: Sage.
• Reviewers: Darkwing and Dewey.

Files owned

• packages/business/src/business.mjs, vars.mjs, vocabulary.mjs, index.mjs and their tests, packages/business/README.md
• packages/harness/src/bundle.mjs, runner.mjs, tests, README
• packages/seat/src/session.mjs and its tests (the family match goes)
• packages/cli/src/launcher.mjs and its tests
• adapters/pi/adapter.sh, adapters/claude/adapter.sh, adapters/README.md
• test business fixtures that set harness, model or thinking
• agents/sage/work/queue-<row>/

What ships

• A top-level routing table in the business file, keyed by role instance name (the keys of roles). Each entry has harness (pi or claude-code), model, family (a key of LAUNCH_CEILING), thinking (the existing six levels), and fallback: null, or an object with the same four keys. Unknown keys refuse. A launch.instances or launch.by name with no entry refuses the business file at load.

• One source. The agent-layer harness, model and thinking vars are removed, and session resolution no longer reads execution.adapter or execution.model. Those system keys stay for scripts/run-task.sh workers, which this row doesn't touch. A business file that still sets the removed vars refuses with a message pointing at routing.

• Resolution. A launch for an instance with no routing entry refuses with no-route. The fallback is used only when the entry states one, and only at launch, when the primary harness fails its preflight (binary missing, or credential status not ok). Never mid-session. The manifest records which entry was used (primary or fallback) and why.

• The launch cap counts sessions by the family of the entry each was launched under. family() in session.mjs goes. launch.max keeps its meaning.

• thinking reaches both harnesses. Pi gets its thinking flag. Claude Code gets its effort or thinking setting. Probe the exact flag or setting on the pinned versions first and record it in the packet and adapters/README.md. The README line saying thinking isn't applied goes.

• First table. The live business file sets nothing today, so this table starts from the row 41 recorded run and the R26 caps. Every fallback is null: a pi fallback on zai/glm-5.3-flash would need a glm family ceiling, which is a separate ruling.

  Role	Harness	Model	Family	Thinking	Fallback
  coder	claude-code	claude-sonnet-5-5	sonnet	medium	none
  reviewer	claude-code	claude-opus-5-5	opus	high	none
  cto	claude-code	claude-opus-5-5	opus	high	none
  pm	claude-code	claude-opus-5-5	opus	high	none

• Tests: a session resolves harness, model and thinking from its table entry; an unknown role or a missing entry refuses the launch; a stated fallback is used when the primary's preflight fails and an unstated one never is; the cap counts by entry family, so a model name holding opus launched under a sonnet entry counts as sonnet; thinking reaches the Pi and Claude Code fake adapters as the recorded flag.

• Gate suites: node --test 'packages/business/tests/*.test.mjs', node --test 'packages/harness/tests/*.test.mjs', node --test 'packages/seat/tests/*.test.mjs', node --test 'packages/cli/tests/*.test.mjs', and every scripts/test-*.sh.

Out of scope

The provider and profile registry in packages/mosaic stays parked; it comes with CLIProxyAPI. Model switching in a running session and the console UI for it (row 29, parked). scripts/run-task.sh worker model selection.

Gate

Darkwing and Dewey approve on the issue, naming the candidate manifest. The suites above pass on a gate rerun in a clean worktree. At landing, Sage writes the first table into mosaic-stack.json and starts one managed coder session, attaching the manifest that shows the entry used, the family counted and the thinking flag passed.

Managed sessions run the unslop check on both harnesses

Problem

tools/unslop-hook checks assistant replies against lists.json, but only as a Pi extension loaded by hand (tools/unslop-hook/README.md). Managed sessions don't load it: the runner passes Pi only the bundle's own extension (packages/harness/src/runner.mjs:223), and the Claude Code bundle has one hook, the PreToolUse gate (packages/harness/src/bundle.mjs:125-127). A managed session can drift into the tells the ms-unslop skill bans and nothing notices.

Owner and reviewer

• Owner: Sage.
• Reviewers: Dewey and Filbert.

Files owned

• tools/unslop-hook/ (a Claude Code hook script beside the extension; the checker and lists.json change only if a test needs it)
• packages/harness/src/bundle.mjs, runner.mjs, tests, README
• adapters/README.md
• agents/sage/work/queue-<row>/

What ships

• Pi. The runner adds tools/unslop-hook/extension.ts to MOSAIC_EXTENSIONS and points MOSAIC_UNSLOP_LOG at <run>/session/unslop.jsonl.
• Claude Code. The bundle's settings.json gains a hook on reply end that checks the last assistant text with unslop-check.js and logs the result, and a hook on the next prompt that adds the correction notice when the last reply was flagged. Same notify-then-correct behaviour as the Pi extension. Neither hook blocks a reply or a turn.
• The operator is told about a flagged reply on the channel mosaic talk already shows session events on. Find that channel and name it in the packet; a notice only in a log file doesn't meet this.
• One lists.json drives both. The manifest records the extension, the hook script and lists.json with digests.
• Fail closed, as the Pi extension does: a broken lists.json stops the checks, logs broken_lists, tells the operator once, and the session keeps running. That includes the headless case the README lists as a limit (print mode notifies nobody); a managed session must reach the operator.
• Counts for a later blocking decision (Q84 option B). unslop.jsonl in the run directory records per-turn checked and flagged events with the pattern ids hit. A test reads the session's checked and flagged counts from it after the session has ended.
• Tests, on both harnesses: a reply with a known tell produces a correction notice on the next turn; a clean reply produces none; a broken lists.json fails closed (no clean verdict, operator told once, session alive); the counts are readable after the session ends.
• Gate suites: node tools/unslop-hook/test-unslop-check.js, node --test 'packages/harness/tests/*.test.mjs', node --test 'packages/cli/tests/*.test.mjs', and every scripts/test-*.sh.

Out of scope

Blocking a reply (Q84 option B), which waits on the measured false-positive rate. Changes to the word lists. The ms-unslop skill itself, which the skills row delivers.

Gate

Dewey and Filbert approve on the issue, naming the candidate manifest. The suites above pass on a gate rerun in a clean worktree. At landing, Sage runs one managed session on each harness with a prompt that draws a known tell, and attaches the operator notice, the next-turn correction and the unslop.jsonl counts.