[Grok/dsh rewrite] Spec: official Rust client with dsh execution core

[Blackman99]

codsh rewrite: upstream Rust client with a dsh execution core

Status: ready-for-agent — scope, testing entry points, and the 80-ticket breakdown approved for publication to Blackman99/codsh on 2026-09-20. Execution remains subject to blockers and separate implementation/release authorization.

This document specifies future work. It does not authorize implementation, source import, deployment, commits, or release. No feature described below is claimed to be implemented by this planning exercise.

Problem Statement

The owner wants codsh to provide the complete feature set and interaction experience of the official Grok CLI while retaining DeepSeek Harness (dsh) as its execution foundation. The current terminal Surface implements selected interactions independently and carries codsh-specific choices, so it cannot provide complete compatibility merely by adding more visual similarities.

A successful rewrite must preserve the official client's observable behavior across terminal interaction, automation, extensions, session lifecycle, and connected services. It must not quietly replace dsh with the official agent runtime, claim equivalence for weaker security, discard existing user data, or call a partial milestone complete.

Solution

Build a separately runnable new codsh by directly reusing and adapting the publicly available, appropriately licensed Rust client source from the official Grok Build repository. Preserve as much of its mature terminal interaction implementation as practical. Replace its execution integration with a codsh-owned adapter to released dsh capabilities.

Grok CLI 1.0.34, locally identified as build 3736acbc8658, remains the frozen behavioral acceptance reference. The imported public source commit is a separately recorded implementation input; public source availability is established, while its precise correspondence to that installed build still requires verification.

The new client retains codsh branding and its command/npm entry point. Users can run it without installing the official Grok executable or obtaining an official account, using explicitly configured model and service providers. Product telemetry defaults and service identities may differ only as explicitly recorded below. Model output quality is evaluated independently from deterministic client behavior.

The old version remains usable while the rewrite develops. Its configuration and original sessions are not modified in place. Migration copies selected data into an isolated dsh Home and Profile, records provenance, and supports returning to the old version. The existing Ship workflow becomes an optional extension rather than a competing default interface.

Scope rule

“All functionality” means every publicly exposed client behavior in the frozen reference, including feature-flag and mode variants that belong to that reference. The story list below is extensive but is not an excuse to omit a command or capability found during inventory. Every discovered behavior must receive a source/reference observation, an implementation ticket, an observable acceptance test, and either evidence of completion or an explicit unresolved blocker. Documentation-only claims, hidden no-op controls, and unsupported stubs do not satisfy final parity.

Domain vocabulary

• Launcher retains the codsh entry point, chooses a compatible installation, and starts the selected client/runtime.
• Bundle supplies codsh's dsh-side integration and Preset; its current same-process terminal responsibility can change in the rewrite.
• Profile is the dsh-owned installation/composition boundary. A separate Profile alone does not isolate all persistent data; the rewrite also has a separate dsh Home.
• Preset composes the model-facing capabilities of a dsh agent.
• Surface, Viewport, Prompt, Transcript, Queue, and Steer retain their domain meanings. Existing keybindings and presentation decisions are legacy-version behavior, not a reason to contradict the new Grok reference.
• Ship names codsh's existing staged development workflow and its optional terminal/browser presentations; it is not the implementation orchestrator for this specification.

User Stories

1. As a terminal user, I want codsh to reproduce the frozen Grok client's complete observable workflows, so that I do not have to learn a second interaction model.
2. As a user, I want codsh's own identity to remain clear, so that I do not mistake it for an officially endorsed distribution.
3. As a maintainer, I want an inventory of every reference command, setting, tool, mode, and service-dependent behavior, so that completeness can be audited rather than inferred from screenshots.
4. As a maintainer, I want the behavioral reference and imported source revision recorded separately, so that source reuse cannot silently move the acceptance target.
5. As a maintainer, I want upstream licenses, applicable notices, and local modifications preserved, so that reused Rust source can be distributed responsibly.
6. As an existing user, I want to install and launch the new client alongside the old one, so that I can try it without losing a working environment.
7. As a new user, I want a stable codsh command and npm installation entry point, so that Rust adoption does not require me to compile the application.
8. As a user, I want a useful welcome and first-run configuration flow, so that missing models or credentials are actionable before I submit work.
9. As a user, I want model requests, tools, sessions, and child agents to execute through dsh, so that the claimed foundation is real and inspectable.
10. As a terminal user, I want streamed answers, thoughts when provided, and tool activity rendered correctly, so that I can follow a running turn.
11. As a terminal user, I want keyboard focus, mouse selection, folding, viewers, and modals to match the reference, so that familiar gestures retain their meaning.
12. As a terminal user, I want multiline editing, undo/redo, history, Vim mode, paste handling, and an external editor, so that I can compose prompts naturally.
13. As a user, I want file and line-range references, hidden-file discovery controls, and drag-and-drop attachments, so that I can provide the intended context accurately.
14. As a terminal user, I want readable Markdown, code, tables, diffs, diagrams, Unicode, and long output, so that content remains usable at different terminal sizes.
15. As a user, I want transcript search, turn navigation, copy, and full-content viewing, so that I can find and reuse earlier work.
16. As a user, I want fullscreen and minimal rendering with reference-compatible in-place switching, so that drafts, queued prompts, and active turns survive a screen-mode change.
17. As a terminal user, I want themes, configurable settings, status-line scripts, and contextual help, so that appearance and session information behave as expected.
18. As a terminal user, I want terminal diagnostics, clipboard fallbacks, SSH/tmux support, notifications, and clean teardown, so that the client works beyond one local terminal emulator.
19. As a user, I want Ctrl+C and other cancellation gestures to have precise reference-compatible behavior, so that clearing a draft does not accidentally cancel work and canceling work does not lose unrelated input.
20. As a user, I want queued prompts to be inspectable, editable, reordered or canceled, so that submitting while the agent works does not lose my intent.
21. As a user, I want to steer a running turn and ask supported side questions, so that I can intervene without confusing the main conversation history.
22. As a user, I want single- and multiple-choice questions, write-in answers, and plan approval, so that required decisions are captured without consuming unrelated queued input.
23. As a user, I want truthful file read/search/edit and shell execution results with inspectable changes, so that I can understand what actually happened on disk.
24. As a user, I want permission modes, remembered approvals, allow/ask/deny rules, and folder trust, so that automation stays within the authority I granted.
25. As an administrator, I want explicit deny rules and hook blocks to survive automatic approval mode, so that convenience cannot bypass hard limits.
26. As a security-conscious user, I want enabled sandbox profiles to enforce their stated process, filesystem, and platform-specific network restrictions, so that their names correspond to real protection.
27. As a user, I want unsupported or failed security enforcement to refuse the requested operation clearly, so that a warning cannot conceal an unconfined execution.
28. As a user, I want session creation, history search, titles, rename, resume, and continue, so that I can return to the correct work.
29. As a user, I want fork and rewind to follow the reference's conversation semantics without silently restoring files, so that history changes have predictable effects.
30. As a user, I want supported session export, sharing, deletion, and disk-management operations, so that I control retained work and understand external disclosure.
31. As a user, I want context inspection and manual/automatic compaction with progress and recovery, so that long conversations remain usable without misleading token reports.
32. As a user, I want model and reasoning-effort selection with advertised capability validation, so that unsupported options are not silently treated as effective.
33. As a user, I want accurate token, cache, cost, and task accounting, so that missing provider information is never displayed as free or fabricated usage.
34. As a user, I want supported custom model protocols and authentication methods, so that I can use my existing dsh-compatible or external routes without an official account.
35. As a user, I want a single effective configuration with inspectable precedence and provenance, so that client and dsh settings cannot disagree invisibly.
36. As an administrator, I want managed defaults, locked requirements, model restrictions, and configurable identity providers, so that organization policies apply consistently to every entry point.
37. As a user, I want existing compatible project instructions, Skills, and agent definitions to be discovered under explicit trust rules, so that I can reuse assets without rewriting them.
38. As a user, I want compatible Hooks and their blocking/result contracts, so that existing automation still governs prompt and tool lifecycles.
39. As a user, I want MCP discovery, tool lookup/calls, initialization state, restart, and failure reporting, so that integrations behave consistently rather than merely appearing in a list.
40. As a user, I want supported MCP remote authentication, structured content, and user elicitation, so that modern integrations work end to end.
41. As a user, I want plugin installation, configuration, enable/disable, and marketplace behavior with clear trust, so that extensions remain manageable.
42. As a user, I want delegated agents with model/type selection and restricted capabilities, so that specialist work is real dsh execution rather than an animated progress label.
43. As a user, I want child transcripts, progress, messaging, cancellation, and resumption where supported, so that I can supervise delegated work.
44. As a user, I want supported isolated git worktrees and clear result application/cleanup, so that parallel changes do not silently overwrite each other.
45. As a user, I want long shell commands to move into the background with output, status, and stop controls, so that I can continue interacting while work runs.
46. As a user, I want monitors and recurring scheduled prompts with visible task state, so that ongoing work can notify the agent without hidden unbounded activity.
47. As a user, I want task completion and event notifications to wake the appropriate session without duplicates, so that I can trust background results.
48. As a user, I want Rhai workflows to execute compatible agent/parallel operations through dsh, so that my existing workflow scripts do not need translation.
49. As a user, I want workflow budgets, concurrency, pause/resume/stop, catalogs, and run views, so that workflow control matches the reference instead of only matching its syntax.
50. As a user, I want plan, goal, and built-in workflow commands to honor their execution and approval contracts, so that planning does not accidentally start implementation.
51. As a user, I want local memory inspection, explicit save/forget, and workspace/global scopes, so that retained knowledge stays understandable and controllable.
52. As a user, I want enabled memory capture, consolidation, and search to use configured providers transparently, so that background processing has known destinations and cost.
53. As a user, I want pasted or attached images to reach a capable configured model with correct preview and failure handling, so that multimodal input is not silently discarded.
54. As a user, I want supported voice input and device diagnostics, so that dictation can be used and canceled with explicit permission and provider routing.
55. As a user, I want web search and fetch with useful sources and actionable errors, so that research works through explicitly configured services.
56. As a user, I want image generation/editing and video generation controls where the reference exposes them, so that multimedia features remain available through replaceable services.
57. As an automation user, I want compatible prompt flags, tool filters, output formats, event ordering, and exit codes, so that changing the executable name does not break my scripts.
58. As an editor user, I want ACP session, streaming, tool, configuration, and permission behavior, so that the same dsh session works through supported IDE clients.
59. As a multi-client user, I want a single execution and durable-write owner per active session, so that reconnects and concurrent views cannot corrupt history or execute the same action twice.
60. As a user, I want local, shared-server, and remote-workspace entry points to report their real capabilities, so that optional daemon or remote behavior never bypasses security.
61. As a user, I want supported remote clone/worktree/workspace operations through configurable substitutes, so that I do not depend on an inaccessible official backend.
62. As a user, I want restart recovery to distinguish saved conversation from still-running work, so that an interrupted external effect is not falsely reported as resumed or exactly-once.
63. As a privacy-conscious user, I want nonessential uploads disabled by default and feedback sent only when I submit it, so that compatibility does not silently disclose my work.
64. As an administrator, I want opt-in diagnostics and observability with explicit destinations and content controls, so that operational insight does not imply permission to upload conversation content.
65. As an existing codsh user, I want selected provider/settings data imported explicitly without changing its source, so that migration remains reversible and does not blindly copy credentials or trust grants.
66. As an existing codsh user, I want session migration to preserve supported content and identify unsupported records, so that partial import never masquerades as a complete restore.
67. As a Ship user, I want the existing workflow available as an optional extension, so that its capability survives without overriding the new default controls.
68. As a Ship user, I want its browser graph and terminal progress to remain consistent after reconnect or resume, so that opting into the extension does not produce contradictory state.
69. As a macOS, Linux, or Windows user, I want prebuilt installation and verified terminal behavior, so that platform support means more than a successful compilation.
70. As a user, I want inspectable version/update behavior and a safe way back to the previous version, so that trying an update does not destroy my environment.
71. As a user, I want responsive startup, input, scrolling, resize, and bounded long-session resource use, so that adding a Rust/dsh boundary does not degrade everyday work materially.
72. As a maintainer, I want deterministic installed-product tests plus real terminal verification and separate model evaluations, so that UI correctness is not confused with model nondeterminism.
73. As a maintainer, I want documentation, release metadata, and dependency/license records to accompany each delivered change, so that a working local build is also a maintainable distribution.
74. As a project owner, I want unresolved dsh gaps, unverified platforms, and service dependencies explicitly listed, so that I decide scope changes instead of discovering hidden omissions after release.
75. As a project owner, I want a complete Rust-to-dsh conversation/tool/approval/cancel/resume demonstration before broad feature work, so that the most important architectural claim is tested early.
76. As a project owner, I want no default-version cutover until all agreed criteria pass, so that staged progress never reduces the original full-parity requirement.

Implementation Decisions

1. Frozen behavior, pinned source. Grok CLI 1.0.34/build 3736acbc8658 is the behavioral reference. Record the exact public source commit and its original monorepo revision separately. Public source exists; determining correspondence is implementation research, not a reason to ask the owner to locate it. Source differences never silently redefine acceptance.
2. Reuse before reimplementation. Start from the official Rust client, including full/minimal rendering and necessary support crates. Keep mature input, layout, focus, rendering, and interaction state machinery wherever viable. Avoid broad mechanical renaming or unnecessary client rewrites. Import only with relevant license/notice provenance and a reviewable local modification history.
3. One execution core. dsh owns actual agent-turn execution, model dispatch, tool execution, session foundations, and child-agent execution. Reused Rust modules can supply presentation, protocol, orchestration, or operating-system mechanisms but cannot introduce a second independently running agent loop, tool authority, or canonical session store.
4. Adapter direction, not unproven equivalence. Use ACP/JSON-RPC as the initial cross-process integration direction. Both sides exposing ACP does not establish version or extension compatibility. Verify capabilities, identifiers, event order, content blocks, approval responses, errors, and cancellation before claiming compatibility. Public proprietary-namespaced extensions are inventoried; private infrastructure internals are not guessed.
5. Single session owner. One live runtime owns execution and durable writes for a session. Other clients observe or request actions through that owner. The protocol must expose reconnect and stale-request outcomes. Do not assume the installed dsh storage provides a complete cross-process lease mechanism merely because relevant error types exist.
6. Incremental installation. Add the new client beside the existing Launcher/Bundle behavior. New dsh Home and Profile isolate data, settings, credentials, plugin composition, and sessions. Preserve the existing release path until the replacement gate passes. Allow package layout changes, platform binaries, and native support components while preserving the codsh command and npm entry point.
7. First integration milestone. Prove launch, a streamed answer, one actual file-tool action with approval, cancellation, process exit, and session restoration through dsh. Use observable provider calls, filesystem effects, and durable session results—not labels saying “dsh”—as proof. This milestone gates feature expansion.
8. Canonical configuration. Expose one effective client configuration, accept supported official-compatible formats and precedence, translate applicable values into dsh configuration, and display origins. Legacy dsh configuration is explicitly imported. Low-level plugin composition is an advanced boundary, not a competing silently authoritative settings file.
9. Models and providers. Preserve dsh provider extensibility and advertised protocol/model capabilities. Map reasoning options explicitly. Unknown usage or incomplete cost remains unknown/incomplete. No hidden provider fallback, automatic official-account reuse, or unconfigured network destination.
10. Security semantics. Permissions, rule evaluation, trust, hooks, and operating-system confinement remain distinct mechanisms. Automatic approval does not bypass explicit denies or required hook blocks. A requested protection that cannot be enforced is refused, never replaced by a misleading UI-only check. The reference's documented platform differences remain visible.
11. Sandbox gap. The installed dsh sandbox contract is per-call subprocess confinement with a file-effect vocabulary; it is not itself proof of whole-process or child-network confinement. Evaluate appropriately licensed Rust confinement support or an upstream/provider extension without forking dsh. Verify actual enforcement across in-process tools, shell children, and child agents. An unavailable required capability blocks completion.
12. Workflow compatibility. Official Rhai scripts and their host contracts are supported without user translation to JavaScript. The existing dsh workflow provider is replaceable, but its current JavaScript engine is not equivalent. Workflow children still execute through dsh; budgets, concurrency, retained results, pause/stop, and same-process resume follow the frozen reference. Do not invent cross-process or exactly-once guarantees.
13. Background ownership. Commands, monitors, scheduler firings, and delegated agents have explicit owners, cancellation paths, completion delivery, and retention. UI disconnect, owner-process exit, session change, and machine restart are different events. Durable scheduling and process-local workflow resumption follow their own verified reference rules rather than a generic “everything resumes” behavior.
14. Session history. Respect dsh append-only history. Use supported fork/projection capabilities to expose compatible conversation operations. Rewind is conversation-only unless the frozen reference explicitly exposes a separate file-restoration operation. Export/delete/share must use explicit user intent, avoid other sessions, and identify service-dependent disclosure.
15. Public compatibility. Preserve applicable flags, output schemas, stream event ordering, error/exit behavior, extension formats, and client interactions. Unsupported provisional features fail explicitly and remain incomplete in the inventory; placeholder success is prohibited. Compatibility names may be retained where existing scripts require them without implying official endorsement.
16. Extension trust. Discover and load compatible instructions, Skills, agent definitions, Hooks, plugins, and MCP assets only under their trust/authorization rules. Preserve lifecycle and result contracts, not just file parsing. Imported assets must not automatically authorize code execution or grant broader tool access.
17. Screen modes. Default fullscreen uses the appropriate alternate-screen lifecycle. Minimal mode intentionally uses native terminal history. Switching preserves the active session, draft, queue, and permission state as required by the reference. Legacy Surface rules that globally forbid native-history output apply to the old implementation, not this mode's new contract.
18. Reference arbitration. For this rewrite, the owner's Grok-specific decisions supersede the existing Claude-first reference arbitration and intentionally divergent legacy keybindings. Record that change in the architecture decision history during implementation. It does not retroactively change the old version's behavior or its prior acceptance records.
19. Service replacement. Authentication, search, media, remote workspaces, feedback, and management endpoints are explicitly configurable. Full completion requires an actual supported substitute for each in-scope service-dependent capability and a verified client flow, not merely a provider interface. Unavailable official privileges, subscription economics, private server implementation, and official trademarks are not reproduced.
20. Privacy defaults. Nonessential telemetry, trace upload, and content sharing default off. Feedback submits only by explicit user action; local drafts remain local. Opt-in observability has visible destinations and content controls. Memory, title/summary, and other background model processing use configured routes and disclose data/cost behavior. These deliberate defaults are recorded compatibility differences.
21. Data migration. Copy selected old configuration and sessions into the new isolated environment; validate, preserve source provenance, and report unsupported data. Original files remain intact. No live dual-writer sync or automatic credential/token transfer. Returning to the old binary must not require it to read the new storage format.
22. Ship extraction. Preserve the existing workflow as an optional extension with non-conflicting command/key registration and consistent terminal/browser state. The default rewrite must run without Ship being loaded. Preserve the existing graph's browser verification requirement when adapting it.
23. Platform distribution. Deliver and test macOS, Linux, and native Windows targets. macOS is the first development environment, not a scope exclusion for the others. Public upstream source build support is not proof that every target is already releasable; Windows-from-source remains a known validation risk.
24. Release discipline. Retain Changesets and existing lockstep package policy until an explicit accompanying release-layout change is delivered. Keep bilingual setup/command documentation and developer build/test instructions synchronized within each implementation slice. Do not create an end-only documentation ticket to excuse missing per-slice docs.
25. Performance. Compare installed products on the same hardware, terminal, data, and deterministic model timing. Measure first-interactive-frame time, input latency, resize/scroll behavior, throughput, and memory/resource growth. Establish and freeze recorded numeric thresholds after measuring the reference baseline and before measuring candidate results; do not select thresholds retrospectively to make a result pass.
26. No unapproved spending or dates. Estimate milestones after reference inventory and architectural validation. Prefer keyless mocks for routine tests. New paid services, resource purchases, or bulk paid evaluation require separate approval.
27. Unresolved work remains visible. A limitation needing dsh upstream support is a blocker, not a completed parity row. Interface feasibility, exact source mapping, kernel support, target buildability, provider availability, and measured thresholds are validation tasks. New product trade-offs require an explicit decision; they are not delegated as implicit implementation choices.

Testing Decisions

Primary external boundary

Prefer one reusable installed-product scenario driver: launch the actual packaged codsh in an isolated workspace and dsh Home, interact through a real pseudo-terminal (PTY) or its public command interface, supply deterministic model/service responses at provider boundaries, and assert observable output plus filesystem/session outcomes. The existing installed-profile harness, pipe tests, terminal session/input/mouse tests, and experience suites provide this precedent.

The Rust client is not mocked in end-to-end tests. dsh executes its real loop and tools; only remote/model/service responses are replaced by controlled fixtures. The official binary or pinned upstream build provides reference observations under equivalent fixtures where possible. Differences that cannot be driven deterministically are explicitly recorded and covered by focused observation rather than invented equivalence.

Necessary complementary boundaries

1. Public protocol clients. Exercise ACP/JSON-RPC and headless formats from an external consumer. Assert initialization/capabilities, session operations, streamed event order, content, errors, permission replies, interruption, reconnect, and exit codes. These are separate product entry points, not tests tied to adapter internals.
2. Security effects. Attempt controlled forbidden reads/writes/renames, child-process operations, and applicable network accesses from tools and subagents. Assert actual denial and unchanged protected state. A matching error string or a visible sandbox badge alone is insufficient.
3. Service integrations. Deterministic fake services cover auth expiry, malformed/partial responses, retries, cancellation, disconnection, and data-routing limits. At least one supported real substitute is exercised for each service-backed capability before it is marked complete.
4. Ship browser extension. When its UI is changed, use the project's browser-testing workflow to operate every affected route and shared state path, including reconnect, resume, missing/long content, desktop, and mobile. Screenshots supplement interaction assertions; they are not the entire test.

Test quality and coverage

• Assert what users or external consumers observe, not private class layouts, function call counts, source-text tokens, or a particular Rust/TypeScript module split.
• Each feature adds its golden path, cancellation/error path, and relevant mode/flag/platform variants. Shared session or configuration changes are verified across every consuming Surface, including terminal, headless, editor, and optional browser views.
• Verify input loss, duplicated execution or notifications, stale approvals, interrupted streams, malformed data, narrow/wide windows, Unicode, large paste, long history, missing credentials, incompatible models, and terminal restoration.
• Use temporary repositories and isolated homes. Never run destructive acceptance tests against the user's project/history or reuse real credentials in fixtures.
• Preserve existing green legacy tests while adding the new path. Existing architecture conflicts are handled as an explicit parallel implementation, not by weakening old tests.
• Reuse upstream public Rust tests/snapshots when applicable, supplementing them with real dsh-backed scenarios; upstream green alone proves neither integration nor service replacement.
• Typecheck and run the workspace test suite, targeted Rust checks/tests/lints, and relevant installed-artifact/PTY integration tests for each delivered implementation slice. Interactive changes require a real terminal exercise.
• Verify clean installation, platform artifact selection, missing/unsupported runtime behavior, upgrade, and rollback; a development-tree launch is insufficient distribution evidence.
• Run controlled concurrency/reconnect tests proving one executor/writer and no duplicate external action. Mark uncertain external effects as interrupted/unknown rather than automatically retrying them.
• Evaluate actual model task success separately with fixed tasks, provider/model/effort configuration, and disclosed costs. UI compatibility does not promise identical model prose.
• Capture repeatable performance measurements and resource cleanup under long sessions and background work. Set numeric acceptance thresholds before measuring the candidate against them.
• Build a coverage register connecting every inventory entry to a story, ticket, test, and evidence. Final release requires no unassigned behavior, no unresolved mandatory blocker, zero failing required checks, and explicit accounting of owner-approved differences.

These test entry points and the 80-ticket breakdown were approved by the owner on 2026-09-20 for GitHub publication. Deterministic behavior tests and real UI verification remain required for implementation acceptance.

Out of Scope

• Replacing dsh's agent execution core with Grok's runtime, forking dsh, or making dsh only a cosmetic model transport.
• A TypeScript reimplementation of the official interface when appropriately licensed Rust can be reused.
• Continuous tracking of future Grok behavior during the frozen-parity effort.
• Official branding/endorsement, subscription entitlements, identical pricing, or reproduction of private official server infrastructure.
• Reproducing model output word-for-word or fabricating reasoning, usage, cost, or capabilities unavailable from a provider.
• Undocumented official binary/asset redistribution without an applicable license.
• Silent weakening of permissions/confinement, silent provider fallback, or default nonessential content upload.
• In-place destructive migration, two versions concurrently writing one session, or automatic backward synchronization of new session data.
• Automatically enabling Ship in the new default interface, deleting the old implementation before cutover, or redesigning unrelated website/demo content.
• New guarantees of exactly-once external effects or cross-process workflow recovery beyond the verified reference.
• Implementation, release publication, remote issue creation, or tracker-configuration edits merely from drafting this document. Those proceed only through their applicable approvals.

Further Notes

Original requirement and confirmed refinement

The owner requested: “现在重新实现这个项目，要求具有 grok 官方 cli 所有的功能以及 UI 体验，但是对接 dsh 基座”. The owner accepted the interview recommendations and explicitly added that direct reuse of official Rust source is acceptable. The owner then requested /to-spec /to-tickets, which authorizes specification and ticket preparation, not an implementation run.

Verified reference facts

• The official public source is xai-org/grok-build. Its README describes client/runtime source exported from the monorepo and first-party Apache-2.0 licensing; third-party components retain their own licenses.
• The inspected public commit a28ee2b2063426e8816e380ccea528b9de95e5da declares client version 1.0.35 and source revision e8563f8f182296ebb53cadb3e1eab7615d76408e. The preceding inspected export 482711333c7195dc16a272777f86086d615e2afb declares 1.0.32. Neither observation proves an exact source match to installed 1.0.34.
• The Rust client declares dependencies on official execution crates. Its separation into named crates is not proof that substituting dsh is a one-line transport change.
• The current project uses released dsh 0.1.5-rc.2. It has session/event, approval, child-agent, ACP/SDK, and workflow extension surfaces, but their exact compatibility must be tested.
• Existing project architecture prioritizes other reference agents and a fullscreen-only Surface. The owner explicitly chose a new reference and both screen modes for this rewrite. The implementation must record scoped supersession rather than silently alter the legacy contract.

Approval and publication

On 2026-09-20 the owner explicitly approved the current testing entry points and 80-ticket breakdown for publication to GitHub Issues in Blackman99/codsh. The specification and tickets use the existing ready-for-agent label and native parent/sub-issue and blocking relationships, with complete blocker references in each ticket body. This publication approval does not start implementation, authorize paid services, or authorize software release. Existing unrelated issues remain unchanged.

Current evidence boundary

Only source/documentation inspection and planning-artifact validation have occurred. There has been no Rust source import, build, application change, model benchmark, operating-system security validation, migration, or release in this task. Those remain acceptance work for the implementation tickets.