[hz89Dev]

Summary

With #1473, a workspace config carries the member settings from ~/.teamai/config.yaml. Several readers still went around that config:

• An AI call read ai.tool straight from files and named ~/.teamai/config.yaml whatever set it.
• A stop hook priced with the user-scope config's modelAliases.
• The votes judge ran on the tool of the working directory.
• A broken workflows.allow on the machine was skipped, which lifted the restriction.
• doctor showed where each setting came from only in --json, and its report (feat(config): show member setting provenance #1474) had no row for sessions, a member setting since fix(config): treat sessions as a member setting so a workspace sees the machine value #1483.

Each reader now takes the loaded config of its scope, so every level of #1459 applies to it.

 callTool(prompt, { launchedBy, scope? })
-  read ai.tool from ~/.teamai/config.yaml and the project file
+  memberTools(scope ?? config resolved for the working directory)
+    TEAMAI_AI_TOOL → ai.tool of the scope's own file → ai.tool of the machine
+    a scope config here that cannot be read → override_invalid, no AI call
+  votes judge passes its hook's scope
 dashboard-report on stop
-  modelAliases of the user-scope config
+  modelAliases of the dispatcher's config (its entries over the machine's)
 workflow <every subcommand, run ids included>
+  machine workflows.allow invalid, or the file unreadable or not YAML → refuse
 doctor (text)
+  "Member settings:" block: value in effect, the level that set it, the levels below,
+    and a value set but not used ("the workspace's auto is not used")
+  usage-reporting note names the level that set it
+  names keys of a ~/.teamai/config.yaml with no install that no command reads
 doctor member settings report (text and --json)
+  sessions.publish.attended / .unattended: SessionPolicy.publish's value, from
+    workspace → machine (unused once the workspace sets sessions) → team → default;
+    an HTTP team repo turns both off, reported as level http-team

26 files, +561/-116.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature causing existing behavior to change)
• Documentation only
• Refactor / internal cleanup

Test Plan

• npx tsc --noEmit passes
• npm run lint passes
• npx vitest run passes. On main 4d3d1f15, the 50 affected test files pass locally (1,621 tests), doctor, session-policy, types.test.ts and the recall tests included. CI runs the full suite.
• Added/updated tests for the change

New tests: tool-launch-call (level order, level-named messages, the pick cache following a changed setting, an unreadable workspace config, a caller's scope), votes-judge and hook-handlers (the judge's scope, stop pricing aliases), workflow-commands (a bad, unknown, unparseable or unreadable machine workflows.allow, and a run-id command), doctor (the text block, one line per alias, the user config named for a machine-wide setting it decides and the workspace value it leaves unused, the sessions.publish row of each run mode and a machine value a workspace's own sessions leaves unused, an empty ai.tool in user scope, the usage note's level, unread machine keys), and local-agent (a settings-only codexTrustEnabled: false). #1473's types.test.ts now checks that every local config key is a member setting or an install key, so I dropped my test for that.

Real CLI, after npm run build. The setup has a settings-only ~/.teamai/config.yaml, no user-scope install, and two workspaces of a local bare team repo whose teamai.yaml turns recall off. Fake codex and claude on PATH log each launch.

Record (macOS, Node 24)

$ cat ~/.teamai/config.yaml
ai:
  tool: codex
recallEnabled: true
excludedSkills: [lint]
sessions:
  publish: { unattended: off }
workflows:
  tools: { default: codex }

$ cd work-a && teamai init https://git.example.com/team/team.git --agent claude
✔ teamai initialized successfully!

$ cd work-b && teamai init https://git.example.com/team/team.git --agent claude
✔ teamai initialized successfully!

$ cd work-a && teamai status | grep -c 'Invalid local config'
0

$ cd work-a && teamai doctor  (Member settings block)
ℹ Member settings:
  ai.tool: codex, from the machine config ~/.teamai/config.yaml
  workflows.tools.default: codex, from the machine config ~/.teamai/config.yaml
  recallEnabled: true, from the machine config ~/.teamai/config.yaml (the team says false)
  sessions.publish.unattended: off, from the machine config ~/.teamai/config.yaml

$ cd work-a && teamai doctor | grep -c 'Invalid local config'
0

$ cd work-a && teamai doctor | grep 'Not read from'
ℹ Not read from ~/.teamai/config.yaml, which holds no user-scope install so only its member settings apply: excludedSkills.

$ cd work-b && teamai import --dir . --all -v   (AI call: which tool ran)
  [debug] [tool-launch] using codex (<fake bin>/codex), from ai.tool (machine)
tools launched:    2 codex 

$ echo 'ai: { tool: claude }' >> <work-a's workspace config>

$ cd work-a && teamai import --dir . --all -v
  [debug] [tool-launch] using claude (<fake bin>/claude), from ai.tool (project)
tools launched:    2 claude 

$ cd work-a && teamai doctor  (Member settings block)
ℹ Member settings:
  ai.tool: claude, from the workspace config ~/.teamai/projects/<work-a>/config.yaml (the machine says codex)
  workflows.tools.default: codex, from the machine config ~/.teamai/config.yaml
  recallEnabled: true, from the machine config ~/.teamai/config.yaml (the team says false)
  sessions.publish.unattended: off, from the machine config ~/.teamai/config.yaml

$ cd work-a && teamai recall disable
✔ Recall disabled. AI tools will no longer auto-search the knowledge base.

$ grep recallEnabled <work-a's workspace config>
recallEnabled: false

$ cd work-a && teamai pull

$ grep -c 'workflows\|recallEnabled: true\|sessions' <work-a's workspace config>  (no machine value copied)
0

$ cd work-a && teamai recall status
Recall: disabled
  Team config (sharing.recall.enabled): false
  User override (recallEnabled): false

$ cd work-b && teamai recall status
Recall: enabled
  Team config (sharing.recall.enabled): false
  User override (recallEnabled): true

$ break work-b's workspace config; cd work-b && teamai import --dir . --all
✖ ~/.teamai/projects/<work-b>/config.yaml: Flow sequence in block collection must be sufficiently indented and end with a ] at line 2, column 1. Fix the file, or move it aside and run `teamai init` to write a new one.
tools launched: 

$ add 'workflows.allow.network: flase' to ~/.teamai/config.yaml; cd work-a && teamai workflow start build --driver local
{"error":{"code":"not_initialized","message":"workflows.allow in ~/.teamai/config.yaml is not valid: network: Expected boolean, received string. A workflow does not run while a restriction it sets may be lifted. Fix or remove it."}}

Not run here: other providers (gitlab, github) and agents (Codex, CodeBuddy, OpenCode). I left those to CI.

Related Issues

Refs #1459, together with #1473 and #1474 (both merged). The "declared once" item of #1459 stays open.

Notes for Reviewers

• Provenance report (feat(config): show member setting provenance #1474, merged). This PR's text block prints doctor's member settings report. Six commits here follow or extend it:
  • The doctor tests expect one line per alias, and the user-scope fixture loads the values its file holds.
  • A scope level that carries ~/.teamai/config.yaml in a workspace is the user scope deciding a machine-wide setting, so the text names it "the user config", not "the workspace config".
  • A level marked used: false reads "the workspace's auto is not used", not "the workspace says auto".
  • sessions.publish.attended and .unattended rows. The effective value comes from SessionPolicy.publish, and each level's value from SessionPolicy.readPublish, so a value publishing ignores never shows as the winner. The defaults moved into SessionPolicy.publishDefaults so doctor reads them rather than copying them.
  • A workspace's own sessions replaces the machine's whole, so the machine's value for a mode the workspace leaves unset is marked unused, and the mode falls to the team or the default.
  • An HTTP team repo keeps no session archive, so SessionPolicy.publish turns both modes off. The report names a new http-team level as the source and marks the values the member set unused.
• Overlap with feat(config): overlay member settings across workspace scopes #1473. feat(config): overlay member settings across workspace scopes #1473 reads codexTrustEnabled for the local agent the same way this branch did, so I dropped my change and kept only its test.
• sessions. fix(config): treat sessions as a member setting so a workspace sees the machine value #1483 made it a member setting on main, so I dropped my commit that kept it with its install, and listed it among the member settings in the docs.
• Invalid machine workflows.allow. feat(config): overlay member settings across workspace scopes #1473 now reads an invalid value as the restrictive one. This PR still refuses before that, with a message naming the file, and also when the file cannot be read or parsed, which feat(config): overlay member settings across workspace scopes #1473's reader treats as no settings.
• Behavior change. An AI call fails with override_invalid when the scope config, or the .git, in its working directory cannot be read. ci extract-mr, the one call that runs without init, used to fall back to the machine's tool in a checkout whose .git git refuses (dubious ownership in some CI containers). It now fails there.
• Error code. A refused workflow command answers with not_initialized, the code loadConfig in workflow-commands.ts already gives every config that cannot be loaded. A new code would change what drivers read.
• No front-end or dashboard change.

[github-actions]

• [P2 non-blocking] Respect machine-wide setting ownership — src/doctor.ts:293: With a user install setting updatePolicy: skip and a workspace setting updatePolicy: auto, doctor reports the workspace’s auto as effective, although the user scope decides this machine-wide setting. autoCompactTokens has the same problem.

• [P2 non-blocking] Ignore empty AI-tool overrides in doctor — src/doctor.ts:304: TEAMAI_AI_TOOL= becomes the reported winner, although memberTools ignores it. An empty scope ai.tool similarly hides a valid machine tool in the report. Match the caller’s nonempty-value checks.

• [P2 non-blocking] Include the recall environment override — src/doctor.ts:286: With recallEnabled: true and TEAMAI_RECALL_DISABLED=1, doctor reports recall as enabled because it checks environment overrides only for ai.tool. Include recall’s disabling override in its effective value and provenance.

• [P2 non-blocking] Include the team’s usage-reporting setting — src/doctor.ts:268: With teamai.yaml containing usageReport: false and no member override, memberSettings reports usageReportEnabled: true from the default. The usage note correctly reports reporting off, so doctor contradicts itself. Map usageReportEnabled to the team’s usageReport.

• [P2 non-blocking] Report all configured workflow entries — src/doctor.ts:217: The fixed key list omits workflows.allow.env and every tool mapping except default. A config containing only workflows.tools.review or workflows.allow.env produces no corresponding provenance, despite the documented per-entry reporting.

The PR description includes sufficient post-build real-CLI verification; no testing blocker. Review was read-only—nothing from the PR was run, built, or installed.

[hz89Dev]

All five are real, and all five sit in code from #1474, which this PR is stacked on. I'm leaving them there for now.

MEMBER_SETTING_REPORT_KEYS and memberSettingsReport (src/doctor.ts:217-319) come in with the #1474 merge at 4f55b225, and no commit after it changes them. This PR's doctor.ts changes are the text renderer above them (memberSettingLines, describeMemberSettingLevel), the usage-reporting note, and the unread-machine-keys note. The text block prints the report's effective value and levels as they are, so it shows the same values doctor --json already emits on #1474.

Each finding, checked against the source:

• updatePolicy / autoCompactTokens: the report never asks which scope decides, so a workspace's own value wins over the user scope's.
• An empty TEAMAI_AI_TOOL or empty scope ai.tool is reported as the winner, though memberTools skips both.
• TEAMAI_RECALL_DISABLED: variable() only knows ai.tool.
• usageReportEnabled: teamValue() has no usageReport mapping, so the report contradicts the usage note.
• workflows.allow.env and workflows.tools.<name> other than default are missing from the fixed key list.

Fixing them in this stacked PR would edit #1474's function while it is still under review. The PR description lists the first two under "Left to #1474". If #1474 merges without these fixes, I'll fix all five here.

[github-actions]

All five earlier findings remain unresolved in the specified diff:

• [P2 non-blocking] Respect machine-wide setting ownership — src/doctor.ts:294: With a user install setting updatePolicy: skip and a workspace setting updatePolicy: auto, doctor reports the workspace’s auto, although user scope owns this machine-wide setting. autoCompactTokens has the same issue.

• [P2 non-blocking] Ignore empty AI-tool overrides — src/doctor.ts:307: TEAMAI_AI_TOOL= is reported as the winner, but memberTools ignores it. An empty scope ai.tool also hides a valid machine tool in the report. Match the caller’s nonempty-value checks.

• [P2 non-blocking] Include the recall environment override — src/doctor.ts:290: With recallEnabled: true and TEAMAI_RECALL_DISABLED=1, doctor reports recall as enabled. Account for the disabling override in both the effective value and provenance.

• [P2 non-blocking] Include the team’s usage-reporting setting — src/doctor.ts:286: With teamai.yaml setting usageReport: false and no member override, the settings report says usageReportEnabled: true from the default, contradicting the usage note. Map this setting to the team’s usageReport.

• [P2 non-blocking] Report all configured workflow entries — src/doctor.ts:221: The fixed key list excludes workflows.allow.env and tool mappings other than default. Configurations containing only these entries receive no provenance, despite the documented per-entry reporting.

No additional confident findings. The PR description includes sufficient post-build real-CLI verification; there is no testing blocker.

Review was read-only: nothing from the PR was run, built, or installed.

[hz89Dev]

These are the same five findings as before. They are still in #1474's memberSettingsReport, which no commit in this PR changes: git diff 9da62e34...HEAD changes only the text renderer (describeMemberSettingLevel, memberSettingLines), the usage note, the unread-machine-keys note and their wiring in doctor() in src/doctor.ts.

#1474 has been asked to fix them as part of its rebase onto main: #1474 (comment). I'll rebase this PR on #1474's fixed head. As I said in #1477 (comment), if #1474 merges without them, I'll fix them here.

[SaulMoro]

This was generated by AI during triage.

@hz89Dev main is red: types.test.ts's key classification from #1473 does not know the sessions key #1478 added, so every PR's Lint & Test fails (main run 40589111091). Your 68c88e6 is the fix ('sessions' in LOCAL_CONFIG_INSTALL_KEYS). Could you open it as its own small PR off main? We will review and merge it right away, and this PR keeps the rest.

[github-actions]

The earlier usage-reporting finding is resolved: usageReportEnabled now maps to the team’s usageReport. Four earlier findings remain:

• [P2 non-blocking] Respect machine-wide setting ownership — src/doctor.ts:298: With a user install setting updatePolicy: skip and a workspace setting updatePolicy: auto, doctor reports the workspace’s auto, although user scope decides this machine-wide setting. autoCompactTokens has the same issue.

• [P2 non-blocking] Ignore empty AI-tool overrides — src/doctor.ts:309: TEAMAI_AI_TOOL= is reported as the winner, but memberTools ignores it. An empty scope ai.tool also hides a valid machine tool in the report. Match the caller’s nonempty-value checks.

• [P2 non-blocking] Include the recall environment override — src/doctor.ts:291: With recallEnabled: true and TEAMAI_RECALL_DISABLED=1, doctor reports recall as enabled. Account for the disabling override in both the effective value and provenance.

• [P2 non-blocking] Report all configured workflow entries — src/doctor.ts:221: The fixed key list excludes workflows.allow.env and tool mappings other than default. Configurations containing only these entries receive no corresponding provenance, despite the documented per-entry reporting.

No additional confident findings. The PR description includes sufficient post-build real-CLI verification; there is no testing blocker.

Review was read-only: nothing from the PR was run, built, or installed.

[SaulMoro]

This was generated by AI during triage.

@hz89Dev #1483 is merged: sessions is now a member setting on main. Please drop e90214d ("keep sessions with its install") when you rebase onto main. With both on main, sessions would be both an install key and a member setting, and the key-ownership test fails on the overlap.

[github-actions]

All five earlier findings are resolved in the specified diff.

• [P2 non-blocking] Preserve literal model-alias keys in provenance — src/doctor.ts:330: An alias such as modelAliases: { "gateway.v1": "claude-sonnet-4" } generates modelAliases.gateway.v1, but key.split('.') treats the alias as nested properties. Doctor therefore omits this configured alias from both text and JSON reports. Look up map-entry names literally rather than splitting their suffixes.

The PR description includes sufficient post-build real-CLI verification; there is no testing blocker.

Review was read-only: nothing from the PR was run, built, or installed.

[hz89Dev]

Confirmed by reading the code: addModelAliasReportKeys adds modelAliases.gateway.v1, and levelsFor splits it into three path parts, finds no level, and the row is dropped. A workflows.tools entry whose name holds a dot is dropped the same way.

Both lines come from #1474 (c8fe2b59 and 75c98eee), which no commit here changes, so the fix belongs there with the other report fixes. I listed it in this PR's description, and I'll fix it here if #1474 merges without it.

[github-actions]

The first five earlier findings are resolved. The dotted-alias finding remains; one additional omission is present:

• [P2 non-blocking] Preserve literal map-entry keys in provenance — src/doctor.ts:330: With modelAliases: { "gateway.v1": "claude-sonnet-4" }, key.split('.') treats the alias as nested properties, so doctor omits it from text and JSON reports. The same lookup affects dotted workflows.tools names. Read map-entry suffixes literally.

• [P2 non-blocking] Include sessions in member-setting provenance — src/doctor.ts:300: A config that sets sessions receives no member-settings row: the fixed key list excludes it, and dynamic enumeration adds only workflow and model-alias entries. Include its configured values and sources to match the documented reporting of every configured member setting.

The PR description includes sufficient post-build real-CLI verification; there is no testing blocker.

Review was read-only: nothing from the PR was run, built, or installed.

[hz89Dev]

Both are real, and both are in #1474's memberSettingsReport, which no commit here changes.

• Dotted map-entry names: unchanged since my last reply, on feat(config): show member setting provenance #1474's new head too.
• sessions: fix(config): treat sessions as a member setting so a workspace sees the machine value #1483 made it a member setting after feat(config): show member setting provenance #1474's fixed key list (MEMBER_SETTING_REPORT_KEYS) was written, so the report has no row for it. A row needs the team level too (teamai.yaml sessions), which SessionPolicy.publish resolves per run mode, so it belongs with the rest of the report's logic.

I listed both in this PR's description as left to #1474. If #1474 merges without them, I'll fix them here.

[github-actions]

The first five findings and the literal dotted-map-key finding are resolved. The sessions finding remains:

• [P2 non-blocking] Include sessions in member-setting provenance — src/doctor.ts:318: A config setting sessions gets no member-settings row in either text or JSON. The fixed key list excludes it, and dynamic enumeration adds only workflows and model aliases. Include its configured values and sources to match the documented reporting of every configured member setting.

No additional confident findings. The PR description includes sufficient post-build real-CLI verification; there is no testing blocker.

Review was read-only: nothing from the PR was run, built, or installed.

[SaulMoro]

This was generated by AI during triage.

@hz89Dev #1474 is merged (a6fd4a0), with the effective-value, two-team, dotted-name and unused-level fixes. Could you rebase this onto main so it carries only its own commits? Note that a level can now carry used: false and one key can have two scope levels, which the text renderer should show. We will review it at the rebased head once its CI review posts.

[github-actions]

All earlier findings are resolved, including sessions provenance.

• [P2 non-blocking] Attribute HTTP publishing overrides correctly — src/doctor.ts:421: With an HTTP team and workspace sessions.publish.unattended: auto, doctor reports off but attributes it to the workspace’s auto setting in both text and JSON. SessionPolicy.publish identifies the actual source as http-team; preserve that provenance and mark the configured value unused.

The PR description includes sufficient post-build real-CLI verification; there is no testing blocker.

Review was read-only: nothing from the PR was run, built, or installed.

[SaulMoro]

This was generated by AI during triage.

@hz89Dev Thanks for the rebase. #1491 landed right after it and also edits src/__tests__/doctor.test.ts (the Copilot fixtures now use path.join(os.tmpdir(), …)), so this conflicts with main there again. Could you rebase once more? Our review is already running at cf26bc0 and will carry over to the rebased head.

[github-actions]

All earlier findings are resolved, including HTTP session-publishing provenance. No additional confident findings in the specified diff.

The PR description includes sufficient post-build real-CLI verification; there is no testing blocker. Additional provider and agent coverage is explicitly deferred to CI.

Review was read-only: nothing from the PR was run, built, or installed.

[SaulMoro]

This was generated by AI during triage.

Approving at c569f73, the rebase onto main after #1491 (range-diff: only the doctor.test.ts imports changed). With the built CLI, against main:

• stop pricing takes the workspace's modelAliases over the machine's (15,000,000 micros here, 3,000,000 on main);
• a bad or unparseable machine workflows.allow refuses workflow start and the run-id commands, which main lets through, and a valid value is not refused;
• the usage note names the machine file when only the machine sets the value (main names the workspace file);
• doctor text and --json agree on five fixtures, including a level marked unused, two scope levels with a user install deciding, dotted names and an empty ai.tool;
• the unread-machine-keys note lists only keys teamai really does not read.

The CI review's HTTP-team sessions.publish attribution reproduced on cf26bc0 and is fixed. 28 new or changed tests fail on main and pass here (886/886, also with a symlinked TMPDIR).

Non-blocking

• [P2 non-blocking] With a user install on another team, the doctor text says "from the team's teamai.yaml" without naming which file (src/doctor.ts:210). The JSON names it, but a member reading the text would open the workspace team's file.
• [P3 nit] Two comments still name the removed aiToolSettings (src/config.ts:425, src/types.ts:840).

#1459 also asks for the member settings to be declared once, as a schema composed into LocalConfigSchema. They are still declared in both places, so I changed the closing line to "Refs #1459". That item can follow separately.