dsh-codespace-workspace 0.1.0 → 0.1.1

package/README.md

@@ -43,14 +43,19 @@ SSH 主机列表里塞任何东西，因此不会和其他云工作区插件冲
   云朵固定不变，不随 Codespace 状态变化。
 - 操作按钮位于**倒数第三个**——在三个点菜单和新建对话按钮之前。
 - 显示逻辑跟随宿主默认行为：不 hover 时隐藏；打开「始终显示」后常显。
-- 按钮状态（四个图标都是**照着宿主图标手绘的 SVG**，不是 emoji）：
+- **正在使用的工作区，云朵和宿主的文件夹图标一样变蓝**：宿主给「拥有当前会话」的那个工作区
+  的图标槽加 `folderActive`，云朵就排在那个槽里，**继承**它的颜色，不自己定颜色。
+- 按钮状态（四个图标都是**照着宿主图标手绘的 SVG**，不是 emoji；转圈用的是宿主自己的
+  `IconLoadingOutline` 圆弧，不是 CSS 方块环）：
 
 | 状态 | 图标 | 悬停提示 | 点击 |
 |---|---|---|---|
 | 已停止 | 播放 | 启动 Codespace | 启动 |
 | 运行中 | 暂停 | 暂停 Codespace | 暂停 |
 | 倒计时中 | 闹钟 | 还剩 X 分钟自动暂停 | 取消倒计时 |
-| 启动/暂停中 | 转圈 | — | 不可点 |
+| 启动/暂停中 | 转圈 | 正在切换状态… | 不可点 |
+
+**转圈只表示「状态正在变化」**，不表示「Agent 正在干活」——后者会让按钮整个回合都在转。
 
 **双击时钟图标 = 立即暂停。**
 
@@ -58,6 +63,9 @@ SSH 主机列表里塞任何东西，因此不会和其他云工作区插件冲
 （`psychic-goggles-7v9974jwpwr5fpqxq`），看不出是哪个项目。标题装不下的两件事放在 hover
 卡片里：那一行「工作区位置」显示 **`owner/name · Codespace 名字`**。
 
+**在 Codespace 会话里发消息时，会先等 Codespace 跑起来**：如果它已经自动暂停（或还在启动），
+这一轮会等到 `Available` 才真正发给模型，而不是让每个工具调用都报连接错误。
+
 ### 新建云端工作区
 
 只有一个窗口，分步显示，不弹一堆窗：
@@ -81,6 +89,10 @@ SSH 主机列表里塞任何东西，因此不会和其他云工作区插件冲
 - **退出 DSH 时**：尝试自动关闭所有本插件管理的 Codespace。
 - **自动暂停**：一轮对话结束后开始倒计时；倒计时期间用户发新消息 → 取消倒计时，
   等 Agent 干完活重新计时；点时钟 → 取消；双击时钟 → 立即暂停。
+- **发消息前保证机器在跑**：挂 `agent/pre-step`（Agent 循环在向模型要 step 之前会
+  **await** 这个 waterfall），发现 Codespace 没运行就先启动、等它变成 `Available`
+  再放行。启动失败或超时不会把这一轮卡死——照常放行，让模型看到真实的连接错误。
+  等待期间你点「停止」/发送中断会立刻结束等待（转发的是这一轮的 abort signal）。
 
 ### Git
 
@@ -201,8 +213,9 @@ test/
 四套离线自检（不需要 token、`gh` 或真实 Codespace），加一套需要令牌的联网自检：
 
 ```bash
-# Node 侧：包清单、Config 默认值、RPC 动作表与 HTTP 守卫、shell 引用、文案一致性
-node test/check.mjs                # 147 项，全通过
+# Node 侧：包清单与打包白名单、Config 默认值、RPC 动作表与 HTTP 守卫、
+# 工作区命名、发消息前的就绪检查、shell 引用、文案一致性
+node test/check.mjs                # 181 项，全通过
 
 # 退出即停：对着真实 CodespaceManager 跑，只把 fetch 换成桩
 node test/shutdown.mjs             # 31 项，全通过
@@ -213,7 +226,7 @@ node test/e2e.mjs                  # 全通过（找不到已安装的 Harness
 
 # 浏览器侧：在真实 DOM 里跑真实 bundle，对着宿主 markup/CSS 的忠实副本
 node test/serve.mjs                # 然后打开 http://127.0.0.1:19501/
-                                   # 203 项，全通过
+                                   # 217 项，全通过
 
 # 联网：用 gh 的令牌打真实 GitHub API（无令牌时自动 SKIP）
 node test/live.mjs
@@ -450,7 +463,7 @@ setPrebuild(data.hasPrebuild === true ? true : false)   // null 被压成 false
   渲染落到「该仓库已配置预构建。」那一支 —— 恰好说了与刚刚相反的话。现在确认后不再显示
   任何提示，而不是显示一句假的。
 
-浏览器套件 136 → **147 项**（后续又涨到 201，见下文「十一」），其中 8 项专测这三态（含
+浏览器套件 136 → **147 项**（后续又涨到 217，见下文「十一」「十三」），其中 8 项专测这三态（含
 「`null` 绝不能说成未配置」和「确认后绝不能说成已配置」两条否定断言）。
 
 **十、云端会话里本地工具根本没让位 —— 提示词说远程，手上还是本地**
@@ -628,6 +641,58 @@ key」：
 浏览器套件 201 → **203 项**。两处都反向验证过牙齿：把 `icon.svg` 从白名单里删掉 → 1 项变红；
 把 hover 那行退回只显示标签 → 1 项变红（`got "my-box", want "Ckarefulon/app.ckarefulon.main · my-box"`）。
 
+**十三、云朵不变蓝、转圈停不下来、转圈是个方块，以及发消息不等机器**
+
+四处都是「照理说应该很明显」的问题，四处的原因各不相同。
+
+**（一）正在使用的工作区里，云朵不变蓝**
+
+宿主是这样标记「当前会话所在的工作区」的：给那一行的**文件夹图标槽**加一个
+`folderActive` 类，规则是 `.…_folderActive{color:var(--dsw-alias-state-business-primary)}`
+—— 也就是变蓝。云朵本来就排在那同一个 span 里、`stroke="currentColor"`，看起来应该自动继承。
+
+问题是**我自己给云朵的容器写了一行 `color: var(--dsw-alias-label-secondary)`**。继承是继承，
+但**显式声明会盖掉继承值**，于是云朵永远是灰的。删掉那行就好——位置、尺寸、颜色、悬停让位
+全都该由宿主的 CSS 说了算。
+
+这条还牵出一个**夹具的老毛病**（这是第三次了，前两次是 16×16 当 28×28、`:hover` 当无条件）：
+夹具里 `.hIlkoa_slot`（设 `label-tertiary`）**排在** `.hIlkoa_folderActive` **后面**，
+而真实宿主里是反过来的。两个都是单类选择器，同优先级，所以**后写的赢** —— 夹具里的
+`folderActive` 根本不起作用，颜色测试一开始是红的。夹具的规则顺序已按宿主改正，并写了注释。
+
+**（二）「正在切换状态…」能转一整个回合**
+
+`isBusy()` 里有一行 `if (record.busy === true) return true`。而 `record.busy` 是
+**host 在 `user/message` 时置位、在 `turn/end` 时清除**的 —— 它的意思是「Agent 正在这个
+工作区里干活」，可以持续好几分钟。把它接进「该不该转圈」里，按钮就会在整个回合里转，还
+配着「正在切换状态…」这句错误的话，而 GitHub 那边的状态其实很明确。现在 `isBusy` 只认两件事：
+**我们自己的 RPC 在飞**，或者 **GitHub 说它确实在过渡态**（`Provisioning`/`Starting`/
+`ShuttingDown`…）。`record.busy` 保留在契约里，只是不再驱动这个按钮。
+
+**（三）转圈图标是个方块**
+
+原来是一个 CSS 环：`border:2px solid; border-top-color:transparent; border-radius:50%`。
+但宿主自己的加载指示器是 **`IconLoadingOutlineRegular`** —— 一段圆圆弧，配一个纯旋转动画
+（在 DSH 自己的 bundle 里核对过）。现在照抄它，于是转圈和那四个状态图标、以及旁边宿主的
+控件是同一套语言（16px、`currentColor`、1px 描边）。顺带补了 `prefers-reduced-motion`。
+
+**（四）发消息时没有等 Codespace 起来**
+
+Codespace 自动暂停之后，直接在会话里发消息，每个远程工具调用都会撞上连接错误。现在挂
+**`agent/pre-step`**：Agent 循环在向模型要 step 之前会 **await** 这个 waterfall
+（`dsh-agent-loop/lib/index.js` ≈L911），所以在这里等是真的在推迟这一轮，而不是和它赛跑。
+DSH 自己的 `archived-session-gate` 用的是同一个钩子 —— 但它是**拦住**这一轮；这里要的是
+**等**，所以拿到结果后照常 `next()`。
+
+几个克制的设计：**本地会话完全不碰**（cwd 判断在最前面）；`ensureRunning` 永不抛错，失败就
+`{ok:false, reason}` 然后照常放行（否则用户会看到一轮莫名其妙地什么都没发生，而不是一个
+明确的连接错误）；等待受这一轮的 abort signal 约束，用户中断立刻结束；成功状态记 20 秒，
+所以一个回合最多查一次 GitHub，而不是每一步都查。
+
+`check` 147 → **181 项**（33 项新增：`ensureRunning` 的各种路径 + `agent/pre-step` 网关的
+行为），浏览器套件 203 → **217 项**。三处都反向验证过牙齿：不启动机器 + 把过渡态当成就绪
+→ 6 项变红；给云朵加回颜色 + 让 `busy` 重新驱动转圈 → 8 项变红。
+
 ## 已知限制
 
 - **工作区分组标题栏的图标行、以及工作区行，都没有官方插槽**。DSH 把「添加工作区」
@@ -671,6 +736,54 @@ key」：
   await 每个 disposer），不是在本机跑一次退出观察到的；本机没有可复现的 Codespace
   目标，无法做端到端退出观察。
 
+## 发布（维护者）
+
+包名 `dsh-codespace-workspace` 已发布到 npm。`package.json` 里写了 `publishConfig`
+（`access: public` + `registry: https://registry.npmjs.org/`），所以**直接 `npm publish`
+不带任何参数**就会发到正确的地方——即使本机 `~/.npmrc` 指向的是镜像站。
+
+> 注意：这个包曾经带 `"private": true`（那时只从 GitHub 装）。npm 会以 `EPRIVATE`
+> 直接拒绝发布，所以该字段已**删除**（不是改成 `false`）。`test/check.mjs` 里有一条
+> 断言专门盯着它「必须不存在」，复制回来会立刻变红。
+
+后续版本**自动发布**：推送到 `main` 时 `.github/workflows/publish.yml` 会先跑测试再
+`npm publish`——但**只有 `package.json` 里的 `version` 是 registry 上还没有的版本时才发**。
+所以发版流程就是两步：
+
+1. 改 `package.json` 的 `version`。
+2. 推送到 `main`。
+
+这次运行要么发出这个版本，要么报告「该版本已在线上」并以成功结束。
+**没改版本号的推送是 no-op，不是失败**——所以每个要发出去的改动都必须自己带一次版本号
+变更；只改文档的提交同样会触发工作流，同样 no-op。
+
+认证用 npm **Trusted Publishing（OIDC）**：GitHub 给这个 job 签一个短时 token，npm 拿它换
+一个只对这一个包有效的发布 token。**仓库里没有任何 `NPM_TOKEN` secret。** 工作流刻意
+**不用** `actions/setup-node` 的 `registry-url` 输入——它会往 `~/.npmrc` 写
+`//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`，而该变量没定义时这个占位符会
+原样留下、被 npm 当作 token 发出去。registry 交给 `publishConfig` 就够了。
+
+工作流在发布前会先 `npm install` 那两个 peer（`@deepseek-ai/cordis`、
+`@deepseek-ai/schemastery`）：本仓库故意不 vendor 它们，而 `test/check.mjs` 是沿着
+import 路径往上找的，装到仓库自己的 `node_modules` 里才能跑到真实模块。
+
+<details>
+<summary>一次性配置：绑定 Trusted Publisher</summary>
+
+Trusted Publisher **只能绑到 registry 上已存在的包**，所以**首次发布是手工做的**
+（在检出目录里跑了一次 `npm publish`），从第二个版本起才轮到工作流接管。在 npmjs.com 上：
+包 → Settings → Trusted Publisher → GitHub Actions，填
+
+| 字段 | 值 |
+|---|---|
+| Repository | `Ckarefulon/dsh-codespace-workspace` |
+| Workflow filename | `publish.yml` |
+| Environment | *留空* |
+
+文件名必须**逐字一致**——npm 把授权绑在它上面，写错会表现为发布报 `ENEEDAUTH`。
+
+</details>
+
 ## 文档
 
 - [`docs/CONTRACT.md`](docs/CONTRACT.md) —— 实现契约：经过核实的 DSH API 事实、

package/lib/client.js

@@ -541,6 +541,18 @@ window.__ModuleLoader__.load({
         viewBox: '0 0 16 16',
         paths: ['M2.5 2.5L13.5 13.5', 'M13.5 2.5L2.5 13.5'],
       },
+      /**
+       * The transitional spinner, `IconLoadingOutlineRegular` verbatim: one round
+       * stroke arc. Deliberately an icon and not a CSS border ring — a ring with
+       * `border-top-color:transparent` is the shape that reads as a square once
+       * the corners are squared off, and it does not match the rest of the set.
+       */
+      loading: {
+        viewBox: '0 0 16 16',
+        paths: [
+          'M12.596 12.596C11.687 13.5049 10.5288 14.1239 9.26798 14.3747C8.00716 14.6255 6.70028 14.4968 5.51261 14.0048C4.32494 13.5129 3.30981 12.6798 2.59557 11.611C1.88134 10.5421 1.50008 9.2855 1.5 7.99998C1.50008 6.71446 1.88134 5.45783 2.59557 4.38898C3.30981 3.32013 4.32494 2.48707 5.51261 1.99513C6.70028 1.50319 8.00716 1.37447 9.26798 1.62524C10.5288 1.87602 11.687 2.49502 12.596 3.40398',
+        ],
+      },
     }
 
     /** Hover delay before a tooltip appears — the host's own header controls use 500ms. */
@@ -655,9 +667,16 @@ window.__ModuleLoader__.load({
       '.dcw-step[data-active="true"] .dcw-step-number{border-color:transparent;background:var(--dsw-alias-state-business-primary);color:var(--dsw-alias-label-primary-inverted)}',
       '.dcw-step-sep{color:var(--dsw-alias-label-tertiary);font-size:11px}',
 
-      /* ---- spinner ---- */
+      /* ---- spinner ---- *
+       * The host's own loading affordance is `IconLoadingOutlineRegular` (a round
+       * stroke arc) paired with a bare rotate animation — not a CSS border ring,
+       * which is what this used to be. Rotating the icon keeps the spinner inside
+       * this plugin's 16px/currentColor icon language, so it matches the four
+       * state glyphs it replaces and the host controls beside it. */
       '@keyframes dcw-spin{to{transform:rotate(360deg)}}',
-      '.dcw-spin{display:inline-block;width:12px;height:12px;border:2px solid var(--dsw-alias-label-tertiary);border-top-color:transparent;border-radius:50%;animation:dcw-spin .8s linear infinite;flex:none}',
+      '.dcw-spin{display:inline-flex;align-items:center;justify-content:center;flex:none;animation:dcw-spin .8s linear infinite}',
+      '.dcw-spin svg{width:14px;height:14px;display:block}',
+      '@media (prefers-reduced-motion:reduce){.dcw-spin{animation:none}}',
 
       /* ---- overlay window ---- */
       '.dcw-overlay{position:fixed;inset:0;z-index:70;display:grid;place-items:center;padding:16px;background:var(--dsw-alias-bg-mask-1,color-mix(in srgb,var(--dsw-alias-label-primary) 40%,transparent))}',
@@ -679,19 +698,34 @@ window.__ModuleLoader__.load({
        *                      color:var(--dsw-alias-label-tertiary);background:0 0;border:none;flex:none;
        *                      justify-content:center;align-items:center;padding:0;display:inline-flex}
        *   .<hash>_iconButton:hover{color:var(--dsw-alias-label-primary)}
-       *   .<hash>_folder{display:none}                     <-- the folder span is hidden in BOTH states
+       *   .<hash>_projectRow .<hash>_chevron{display:none}
+       *   .<hash>_projectRow:hover .<hash>_chevron{display:inline-flex}
        *   .<hash>_projectRow:hover .<hash>_folder{display:none}
+       *   .<hash>_folderActive{color:var(--dsw-alias-state-business-primary)}
+       * NOTE the folder rules: the folder is VISIBLE at rest and only steps aside
+       * on hover. There is no unconditional `.<hash>_folder{display:none}` — an
+       * earlier revision read the hover rule as one and concluded there was no
+       * folder to replace. `folderActive` is added by the host to that same span
+       * for the workspace owning the current session, and its colour is what the
+       * cloud inherits (so do NOT set a colour here).
        * The hashed prefix (`hIlkoa_`) is per build, so every selector below matches
        * the class name by suffix via [class*="_name"]. The stable hooks are
        * `data-row-key` (host-rendered) and the `data-dsh-codespace-*` attributes
        * this bundle adds.
        * ------------------------------------------------------------------ */
-      '[data-dsh-codespace-icon]{width:16px;height:20px;color:var(--dsw-alias-label-secondary);flex:none;display:inline-flex;align-items:center;justify-content:center;pointer-events:none}',
+      /* No `color` here on purpose. The host marks the workspace that owns the
+       * current session by adding `folderActive` to this very span, and that rule
+       * is `.…_folderActive{color:var(--dsw-alias-state-business-primary)}` — the
+       * blue every other active row shows. Setting a colour of our own would
+       * OVERRIDE that inherited value and leave the cloud grey while the folder
+       * beside it, in another workspace, turned blue. Inherit: the span supplies
+       * `label-tertiary` at rest and the business colour when active. */
+      '[data-dsh-codespace-icon]{width:16px;height:20px;flex:none;display:inline-flex;align-items:center;justify-content:center;pointer-events:none}',
       '[data-dsh-codespace-icon] svg{width:16px;height:16px;display:block}',
       '[data-dsh-codespace-action]{display:inline-flex;align-items:center;justify-content:center;width:16px;height:16px;padding:0;border:0;border-radius:var(--dsw-radius-xs,4px);background:0 0;color:var(--dsw-alias-label-tertiary);font:inherit;font-size:12px;line-height:1;cursor:pointer;flex:none}',
       '[data-dsh-codespace-action]:hover:not(:disabled){color:var(--dsw-alias-label-primary)}',
       '[data-dsh-codespace-action]:disabled{cursor:default;opacity:.6}',
-      '[data-dsh-codespace-action] .dcw-spin{width:10px;height:10px;border-width:1.5px}',
+      '[data-dsh-codespace-action] .dcw-spin svg{width:14px;height:14px}',
       '[data-dsh-codespace-glyph]{display:inline-block;font-size:12px;line-height:1}',
       /* `alwaysShowCloudButton`: the container is `display:none` when the row is
        * not hovered, and a `display:none` ancestor cannot be overridden from a
@@ -928,10 +962,25 @@ window.__ModuleLoader__.load({
       return Math.max(0, at - Date.now())
     }
 
-    /** Whether the row button must show a spinner. */
+    /**
+     * Whether the row button must show a spinner — i.e. whether a STATE CHANGE is
+     * in flight.
+     *
+     * `record.busy` is deliberately NOT consulted. The host sets it on
+     * `user/message` and clears it on `turn/end`, so it means "the agent is
+     * working in this workspace" — which can be minutes. Feeding that into this
+     * predicate made the row spin with the tooltip 「正在切换状态…」 for the whole
+     * turn even though GitHub was reporting a settled state, which is precisely
+     * the "it keeps spinning but the state is clear" complaint. Here only two
+     * things matter: our own RPC is in flight, or GitHub says the Codespace is
+     * genuinely mid-transition (`Provisioning`/`Starting`/`ShuttingDown`/…).
+     *
+     * @param {object} record - a `Managed` record.
+     * @param {Set<string>} pendingIds - workspace ids with an in-flight action.
+     * @returns {boolean} whether to spin.
+     */
     function isBusy(record, pendingIds) {
       if (pendingIds.has(record.workspaceId)) return true
-      if (record.busy === true) return true
       return phaseOf(record) === 'pending'
     }
 
@@ -2279,7 +2328,7 @@ window.__ModuleLoader__.load({
               ? h(
                   'div',
                   { className: 'dcw-row' },
-                  h('span', { className: 'dcw-spin' }),
+                  h('span', { className: 'dcw-spin' }, h(Icon, { kind: 'loading', size: 16 })),
                   h('span', null, stage === '' ? t('apply.creating') : stage),
                 )
               : h(
@@ -2783,6 +2832,7 @@ window.__ModuleLoader__.load({
             const spinner = doc.createElement('span')
             spinner.className = 'dcw-spin'
             spinner.setAttribute('aria-hidden', 'true')
+            spinner.appendChild(iconNode(ACTION_ICONS.loading))
             button.appendChild(spinner)
           } else {
             // A hand-drawn DSH icon, NOT an emoji: the two buttons beside this one

package/lib/host/codespaces.js

@@ -27,7 +27,7 @@ import { homedir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import { randomUUID } from 'node:crypto'
 
-import { PLACEHOLDER_DIRNAME, SETTINGS_DEFAULTS, codespacePhase, redact, wireError } from '../shared.js'
+import { PLACEHOLDER_DIRNAME, SETTINGS_DEFAULTS, canStart, codespacePhase, redact, wireError } from '../shared.js'
 import {
   createCodespace,
   deleteCodespace,
@@ -55,6 +55,23 @@ const STOP_ONE_BUDGET_MS = 3500
 /** Name of the persisted workspace↔Codespace map inside the placeholder root. */
 const MAP_FILENAME = '.managed.json'
 
+/**
+ * How long a "this Codespace is running" observation is trusted.
+ *
+ * A turn asks {@link CodespaceManager.ensureRunning} before every model step, and
+ * re-listing the account's Codespaces each time would be both slow and rude. A
+ * running Codespace stays running for minutes, so a short window is enough to
+ * collapse a whole turn into at most one check while still noticing an
+ * auto-pause promptly. Every path that stops a Codespace invalidates it anyway.
+ */
+const RUNNING_MEMO_MS = 20 * 1000
+
+/** How long to wait for a Codespace to become usable before giving up on it. */
+const START_TIMEOUT_MS = 5 * 60 * 1000
+
+/** Delay between state polls while waiting for a Codespace to come up. */
+const START_POLL_MS = 3000
+
 /** Default README committed into a repository that has no commits. */
 const DEFAULT_README = [
   '# Codespace workspace',
@@ -115,6 +132,37 @@ export function resolveProfileHome(ctx) {
   return resolve(homedir())
 }
 
+/**
+ * Sleep, for the state-polling loop in {@link CodespaceManager.ensureRunning}.
+ *
+ * The timer is deliberately **not** `unref()`d: an unref'd timer lets a process
+ * with nothing else pending exit instead of waiting, which is exactly how a test
+ * of this loop would silently stop testing anything. Cancellation is handled by
+ * the signal instead, so a shutdown never waits out a poll.
+ *
+ * @param {number} ms - how long to wait.
+ * @param {AbortSignal} [signal] - cut the wait short when this aborts.
+ * @returns {Promise<void>} resolves on timeout or abort.
+ */
+function sleep(ms, signal) {
+  return new Promise((resolve_) => {
+    if (signal?.aborted === true) {
+      resolve_()
+      return
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener?.('abort', onAbort)
+      resolve_()
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener?.('abort', onAbort)
+      resolve_()
+    }, ms)
+    signal?.addEventListener?.('abort', onAbort, { once: true })
+  })
+}
+
 /** Make one directory-name-safe token out of a Codespace name. */
 function safeDirName(name) {
   const cleaned = String(name).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '')
@@ -187,6 +235,12 @@ export class CodespaceManager {
     this.busy = new Set()
     /** @type {Set<string>} */
     this.inFlight = new Set()
+    /**
+     * Codespace name → `Date.now()` until which "it is running" may be assumed.
+     * See {@link RUNNING_MEMO_MS}.
+     * @type {Map<string, number>}
+     */
+    this.runningUntil = new Map()
     /** @type {Promise<object>|undefined} Set by the first {@link CodespaceManager.stopAll} call. */
     this.stopAllPromise = undefined
     this.disposed = false
@@ -468,10 +522,108 @@ export class CodespaceManager {
     return { ...row, managed: this.isManaged(row.name) }
   }
 
+  /** Forget a remembered "running" observation. */
+  forgetRunning(name) {
+    this.runningUntil.delete(name)
+  }
+
+  /**
+   * The live Codespace row for one name, or `null` when GitHub no longer has it.
+   *
+   * @param {string} name - the Codespace name.
+   * @returns {Promise<object|null>} the normalized row.
+   */
+  async liveCodespace(name) {
+    const rows = await this.listCodespaces()
+    return rows.find((row) => row.name === name) ?? null
+  }
+
+  /**
+   * Make sure one workspace's Codespace is running, starting it when it is not.
+   *
+   * This is what lets a user just type into a Codespace session whose Codespace
+   * is asleep: the message waits for the machine instead of failing every tool
+   * call with a connection error. It is called from the `agent/pre-step`
+   * waterfall, which the agent loop **awaits** before it asks the model for a
+   * step (verified in `dsh-agent-loop/lib/index.js` ≈L911), so returning late
+   * genuinely delays the turn rather than racing it.
+   *
+   * Never throws: a Codespace that cannot be started is reported as
+   * `{ ok: false, reason }` and the turn proceeds, so the model sees the real
+   * transport error rather than a silently blocked turn.
+   *
+   * @param {string} workspaceId - the managed workspace id.
+   * @param {{signal?: AbortSignal, timeoutMs?: number, pollMs?: number}} [options] - bounds.
+   * @returns {Promise<{ok: boolean, reason: string, state?: string}>} the outcome.
+   */
+  async ensureRunning(workspaceId, options = {}) {
+    const record = this.recordOf(workspaceId)
+    if (record === undefined) return { ok: false, reason: 'unmanaged' }
+
+    const signal = options.signal
+    const remembered = this.runningUntil.get(record.name)
+    if (remembered !== undefined && Date.now() < remembered) return { ok: true, reason: 'remembered' }
+
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : START_TIMEOUT_MS
+    const pollMs = Number.isFinite(options.pollMs) ? options.pollMs : START_POLL_MS
+    const deadline = Date.now() + Math.max(0, timeoutMs)
+    const aborted = () => signal?.aborted === true
+
+    let row
+    try {
+      row = await this.liveCodespace(record.name)
+    } catch (error) {
+      return { ok: false, reason: 'unreachable', state: error instanceof Error ? error.message : String(error) }
+    }
+    if (row === null) return { ok: false, reason: 'missing' }
+    if (codespacePhase(row.state) === 'running') {
+      this.runningUntil.set(record.name, Date.now() + RUNNING_MEMO_MS)
+      return { ok: true, reason: 'running' }
+    }
+
+    // Start it when GitHub says that is a legal thing to ask for. A `pending`
+    // state means the transition is already under way, so it is waited out
+    // rather than re-requested.
+    let started = false
+    if (canStart(codespacePhase(row.state))) {
+      if (aborted()) return { ok: false, reason: 'aborted', state: row.state }
+      this.log('info', `starting ${record.name} because a turn needs it (state ${row.state})`)
+      try {
+        await this.start(record.name)
+        started = true
+      } catch (error) {
+        return { ok: false, reason: 'start-failed', state: error instanceof Error ? error.message : String(error) }
+      }
+    }
+
+    let last = row.state
+    while (Date.now() < deadline) {
+      if (aborted()) return { ok: false, reason: 'aborted', state: last }
+      await sleep(pollMs, signal)
+      if (aborted()) return { ok: false, reason: 'aborted', state: last }
+      try {
+        row = await this.liveCodespace(record.name)
+      } catch (error) {
+        return { ok: false, reason: 'unreachable', state: error instanceof Error ? error.message : String(error) }
+      }
+      if (row === null) return { ok: false, reason: 'missing' }
+      last = row.state
+      const phase = codespacePhase(row.state)
+      if (phase === 'running') {
+        this.runningUntil.set(record.name, Date.now() + RUNNING_MEMO_MS)
+        this.log('info', `${record.name} is available${started ? ' after starting it' : ''}`)
+        return { ok: true, reason: started ? 'started' : 'became-running' }
+      }
+      if (phase === 'error') return { ok: false, reason: 'failed', state: row.state }
+    }
+    return { ok: false, reason: 'timeout', state: last }
+  }
+
   /** Stop a Codespace and cancel any pending auto-pause for it. */
   async stop(name) {
     const record = this.recordByName(name)
     if (record !== undefined) this.cancelAutoPause(record.workspaceId)
+    this.forgetRunning(name)
     const { token } = await this.requireToken()
     const row = await stopCodespace(token, name)
     return { ...row, managed: this.isManaged(row.name) }
@@ -481,6 +633,7 @@ export class CodespaceManager {
   async remove(name) {
     const record = this.recordByName(name)
     if (record !== undefined) this.cancelAutoPause(record.workspaceId)
+    this.forgetRunning(name)
     const { token } = await this.requireToken()
     await deleteCodespace(token, name)
   }
@@ -785,6 +938,9 @@ export class CodespaceManager {
     this.cancelAutoPause(workspaceId)
     const record = this.records.get(workspaceId)
     if (record === undefined) return { stopped: false, name: '' }
+    // The memo must not outlive a stop we asked for: a turn starting right after
+    // an auto-pause has to see the stopped state and start the machine again.
+    this.forgetRunning(record.name)
 
     try {
       const { token } = await this.requireToken()
@@ -836,6 +992,7 @@ export class CodespaceManager {
 
     const names = [...new Set([...this.records.values()].map((record) => record.name))]
     if (names.length === 0) return { attempted: 0, stopped: 0, pending: [] }
+    for (const name of names) this.forgetRunning(name)
 
     let token = null
     try {
@@ -938,5 +1095,6 @@ export class CodespaceManager {
     this.disposed = true
     for (const workspaceId of [...this.timers.keys()]) this.cancelAutoPause(workspaceId)
     this.busy.clear()
+    this.runningUntil.clear()
   }
 }

package/lib/host/session.js

@@ -189,6 +189,40 @@ export function installSessionWiring(ctx, manager, options = {}) {
     dispose()
   })
 
+  // ------------------------------------------------- make the machine ready
+  //
+  // A Codespace that has auto-paused must be running before the model asks for
+  // anything, or every remote tool call in the turn fails with a connection
+  // error. `agent/pre-step` is the right place: the agent loop **awaits** this
+  // waterfall before it requests a step (verified in `dsh-agent-loop/lib/index.js`
+  // ≈L911), so returning late genuinely delays the turn instead of racing it. The
+  // archived-session gate in `dsh-api-session-controller` uses the same hook — to
+  // BLOCK a step; blocking is not what we want, because the user asked for the
+  // message to WAIT.
+  //
+  // Local sessions are untouched: the cwd check comes first and is cheap. The
+  // whole body is caught, because a throwing listener here would break the turn
+  // rather than delay it, and `next()` is always called so the decision chain
+  // still runs.
+  const preStepEffect = ctx.on('agent/pre-step', async (payload, next) => {
+    if (disposed) return next()
+    try {
+      const agent = payload?.agent
+      const workspaceId = manager.isCodespacePath(agent?.session?.header?.cwd)
+      if (workspaceId !== undefined) {
+        const outcome = await manager.ensureRunning(workspaceId, { signal: payload?.signal })
+        if (outcome.ok !== true) {
+          // Not fatal: the turn proceeds, and the model sees the real transport
+          // error rather than a turn that silently never starts.
+          log('warn', `a turn is starting while its Codespace is not usable (${outcome.reason}${outcome.state === undefined ? '' : `: ${outcome.state}`})`)
+        }
+      }
+    } catch (error) {
+      log('warn', `pre-step readiness check failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    return next()
+  })
+
   // ------------------------------------------------------------- auto-pause
 
   /**
@@ -248,7 +282,7 @@ export function installSessionWiring(ctx, manager, options = {}) {
     if (torn) return
     torn = true
     disposed = true
-    for (const dispose of [createdEffect, disposedEffect, eventEffect, promptEffect, shutdownEffect]) {
+    for (const dispose of [createdEffect, disposedEffect, eventEffect, preStepEffect, promptEffect, shutdownEffect]) {
       try {
         if (typeof dispose === 'function') dispose()
       } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-codespace-workspace",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Use a GitHub Codespace directly as a DSH workspace: the agent reads, writes and runs commands inside the cloud Codespace.",
   "type": "module",
   "license": "MIT",