[wSedlacek]

Reopened from closed upstream PR pingdotgg#34628 as a draft for t3.1code.
Idea rank: 28 of 108. Branch is as it was upstream; it likely needs a rebase (modernize) before review.

Problem

Agents dropped into a project often either under-orient (missing README/architecture/progress) or over-stuff the context window by loading every doc. There is no shared trailhead that says what to read first and what to do when those routes run out.

Approach

• Add repo-local starting-map discovery (.agents/STARTING_MAP.md, then AGENTS.md / README / architecture / progress / area docs / roster) that returns routes only, never file contents.
• Add MCP tool t3_project_orient (whoami + present routes + whenMapRunsOut guidance).
• Nudge orchestration instructions to call it once before substantive work.
• Ship this repo's own .agents/STARTING_MAP.md as the convention example.
• Raise agentContextBudget.json for the new tool schema and instruction line (needs agent-context-increase).

Scope (approved plan)

• This PR is agent orientation only (trailhead + MCP affordance).
• No map dashboard UI.
• Share starting-map / trailhead references with team templates (feat(orchestration): add specialists from Workshop or repo bundles pingdotgg/t3code#34618) when that work absorbs bundles; keep the orientation surface here.

OpenRig inspiration

OpenRig's starting map: a short trailhead (whoami → README/architecture/progress → area docs) plus explicit "when the map runs out" (search, roster, report missing route) for minimum viable competence without filling the window.

Test plan

• vp test run apps/server/src/project/StartingMap.test.ts
• vp test run apps/server/src/mcp/toolkits/project/handlers.test.ts -t t3_project_orient
• vp run check:changed
• Call t3_project_orient in a live thread; confirm routes mark .agents/STARTING_MAP.md present and response has no file bodies
• Follow a present route with Read; confirm "when the map runs out" guidance is actionable
• Apply agent-context-increase label (budget grew for tool list + orchestration append)

🤖 Generated with Claude Code

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	21.5 KiB	21.5 KiB	0 B (0.0%)	24.4 KiB	✅
Codex	Live turn messages	1	1	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.9 KiB	21.9 KiB	0 B (0.0%)	24.4 KiB	✅
Claude	Live turn messages	1	1	0 (0.0%)	8	✅

Other scenarios

All 64 scenario measurements match main.

All 64 scenario measurements

Provider	Scenario	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	short turn resume	WebSocket decoded	10.5 KiB	10.5 KiB	0 B (0.0%)	12.7 KiB	✅
Codex	short turn resume	WebSocket messages	2	2	0 (0.0%)	2	✅
Codex	long turn running, cold open	HTTP decoded	281.7 KiB	281.7 KiB	0 B (0.0%)	302.7 KiB	✅
Codex	long turn running, cold open	rows	75	75	0 (0.0%)	75	✅
Codex	long turn running, history page	HTTP decoded	92.4 KiB	92.4 KiB	0 B (0.0%)	107.4 KiB	✅
Codex	long turn running, history page	rows	75	75	0 (0.0%)	75	✅
Codex	long turn finished, cold open	HTTP decoded	381.5 KiB	381.5 KiB	0 B (0.0%)	410.2 KiB	✅
Codex	long turn finished, cold open	rows	151	151	0 (0.0%)	151	✅
Codex	long turn finished, socket cold open	WebSocket decoded	381.6 KiB	381.6 KiB	0 B (0.0%)	410.2 KiB	✅
Codex	long turn finished, socket cold open	WebSocket messages	2	2	0 (0.0%)	2	✅
Codex	long turn finished, socket cold open	rows	151	151	0 (0.0%)	151	✅
Codex	long turn finished, work page	HTTP decoded	186.2 KiB	186.2 KiB	0 B (0.0%)	200.2 KiB	✅
Codex	long turn finished, work page	rows	150	150	0 (0.0%)	150	✅
Codex	idle thread resume	WebSocket decoded	65 B	65 B	0 B (0.0%)	200 B	✅
Codex	idle thread resume	WebSocket messages	1	1	0 (0.0%)	1	✅
Codex	fleet shell snapshot	HTTP decoded	42.4 KiB	42.4 KiB	0 B (0.0%)	53.7 KiB	✅
Codex	fleet shell snapshot	rows	27	27	0 (0.0%)	27	✅
Codex	fleet shell subscribe	WebSocket decoded	65 B	65 B	0 B (0.0%)	200 B	✅
Codex	fleet shell subscribe	WebSocket messages	1	1	0 (0.0%)	1	✅
Codex	fleet shell resume check	HTTP decoded	18 B	18 B	0 B (0.0%)	100 B	✅
Codex	fleet shell resume check	rows	0	0	0	0	✅
Codex	stale shell reload	HTTP decoded	42.4 KiB	42.4 KiB	0 B (0.0%)	53.7 KiB	✅
Codex	stale shell reload	rows	27	27	0 (0.0%)	27	✅
Codex	stale shell resume	WebSocket decoded	140 B	140 B	0 B (0.0%)	400 B	✅
Codex	stale shell resume	WebSocket messages	2	2	0 (0.0%)	2	✅
Codex	stale todo list cold open	HTTP decoded	72.4 KiB	72.4 KiB	0 B (0.0%)	83.0 KiB	✅
Codex	stale todo list cold open	rows	75	75	0 (0.0%)	75	✅
Codex	stale todo list cold open	nodes	2	2	0 (0.0%)	4	✅
Codex	stale todo list cold open	subagents	2	2	0 (0.0%)	4	✅
Codex	stale todo list cold open	plans	1	1	0 (0.0%)	2	✅
Codex	stale todo list cold open	providerTurns	1	1	0 (0.0%)	2	✅
Codex	stale todo list cold open	checkpoints	1	1	0 (0.0%)	2	✅
Claude	short turn resume	WebSocket decoded	10.6 KiB	10.6 KiB	0 B (0.0%)	12.7 KiB	✅
Claude	short turn resume	WebSocket messages	2	2	0 (0.0%)	2	✅
Claude	long turn running, cold open	HTTP decoded	283.3 KiB	283.3 KiB	0 B (0.0%)	302.7 KiB	✅
Claude	long turn running, cold open	rows	75	75	0 (0.0%)	75	✅
Claude	long turn running, history page	HTTP decoded	93.4 KiB	93.4 KiB	0 B (0.0%)	107.4 KiB	✅
Claude	long turn running, history page	rows	75	75	0 (0.0%)	75	✅
Claude	long turn finished, cold open	HTTP decoded	384.2 KiB	384.2 KiB	0 B (0.0%)	410.2 KiB	✅
Claude	long turn finished, cold open	rows	151	151	0 (0.0%)	151	✅
Claude	long turn finished, socket cold open	WebSocket decoded	384.3 KiB	384.3 KiB	0 B (0.0%)	410.2 KiB	✅
Claude	long turn finished, socket cold open	WebSocket messages	2	2	0 (0.0%)	2	✅
Claude	long turn finished, socket cold open	rows	151	151	0 (0.0%)	151	✅
Claude	long turn finished, work page	HTTP decoded	188.1 KiB	188.1 KiB	0 B (0.0%)	200.2 KiB	✅
Claude	long turn finished, work page	rows	150	150	0 (0.0%)	150	✅
Claude	idle thread resume	WebSocket decoded	66 B	66 B	0 B (0.0%)	200 B	✅
Claude	idle thread resume	WebSocket messages	1	1	0 (0.0%)	1	✅
Claude	fleet shell snapshot	HTTP decoded	43.0 KiB	43.0 KiB	0 B (0.0%)	53.7 KiB	✅
Claude	fleet shell snapshot	rows	27	27	0 (0.0%)	27	✅
Claude	fleet shell subscribe	WebSocket decoded	66 B	66 B	0 B (0.0%)	200 B	✅
Claude	fleet shell subscribe	WebSocket messages	1	1	0 (0.0%)	1	✅
Claude	fleet shell resume check	HTTP decoded	18 B	18 B	0 B (0.0%)	100 B	✅
Claude	fleet shell resume check	rows	0	0	0	0	✅
Claude	stale shell reload	HTTP decoded	43.0 KiB	43.0 KiB	0 B (0.0%)	53.7 KiB	✅
Claude	stale shell reload	rows	27	27	0 (0.0%)	27	✅
Claude	stale shell resume	WebSocket decoded	140 B	140 B	0 B (0.0%)	400 B	✅
Claude	stale shell resume	WebSocket messages	2	2	0 (0.0%)	2	✅
Claude	stale todo list cold open	HTTP decoded	73.4 KiB	73.4 KiB	0 B (0.0%)	83.0 KiB	✅
Claude	stale todo list cold open	rows	75	75	0 (0.0%)	75	✅
Claude	stale todo list cold open	nodes	2	2	0 (0.0%)	4	✅
Claude	stale todo list cold open	subagents	2	2	0 (0.0%)	4	✅
Claude	stale todo list cold open	plans	1	1	0 (0.0%)	2	✅
Claude	stale todo list cold open	providerTurns	1	1	0 (0.0%)	2	✅
Claude	stale todo list cold open	checkpoints	1	1	0 (0.0%)	2	✅

Baseline: 7fd5a75 · PR result: 5004e3f · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.