piher 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# piher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pi extension behind **piher**: it registers the `subagent` and `bg_job` tools and runs what they
+start as [herdr-core](https://herdr.dev/) (`hc`) terminals, which the optional **Herdr app** shows as
+spaces, tabs and panes.
+
+A subagent is a separate pi session in its own terminal — its own context, visible in the app, and
+attachable by a human at any time. Inside a core terminal (`HC_TERMINAL_ID` / `HC_TERMINAL_SOCKET`)
+both tools are live; outside one they are not registered, and the extension only replays what a
+transcript already recorded.
+
+## Install
+
+```sh
+curl -fsSL https://releases.herdr.dev/core/install.sh | sh   # herdr-core, required for the tools
+pi install npm:piher                                        # this package
+```
+
+`pi update --extensions` updates it, `pi remove npm:piher` removes it. Without `hc` the package still
+loads and both tools answer with that install command instead of running anything.
+
+## What it registers
+
+| Surface | Names |
+|---|---|
+| Tools | `subagent` (`spawn`, `send`, `retry`, `output`, `list`, `interrupt`, `resume`, `close`, `help`), `bg_job` (`start`, `status`, `log`, `stop`, `list`) |
+| Commands | `/piher-role`, `/piher-config`, `/piher-locks` |
+| Skill | `piher-tools` — when to delegate, what a prompt must contain, the answer-or-`BLOCKED:` report contract |
+| Session entries | `piher.delegation`, `piher.settlement`, `piher.role-manifest`, `piher.job-exit`, `piher.config-guide` |
+| Terminal labels | `piher.session`, `piher.lock.<hash>` |
+
+## Package contents
+
+```
+src/          # the extension
+src/roles/    # bundled role manifests (master, worker-default)
+schemas/      # role-manifest JSON schema
+skills/       # the shipped skill
+test/         # node --test suites
+```
+
+## Requirements
+
+- Node ≥ 22
+- pi ≥ 1.4.0 (`@earendil-works/pi-coding-agent`) — its native OSC 7501 reporter is the only status source
+- herdr-core `hc` ≥ 0.1.16 — required for both tools
+- Herdr app (optional) — display only
+
+## Development
+
+```sh
+npm install --ignore-scripts      # from the repository root
+npm test                          # typecheck + node --test
+```
+
+The repository README covers the architecture, roles, the task documents, configuration and the
+plugin-conflict rules.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "piher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "piher: registers the subagent and terminal tools in pi and runs them as herdr-core terminals shown by the Herdr app",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "herdr-core",
+    "herdr-app",
+    "coding-agent",
+    "subagents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felixzsh/piher.git",
+    "directory": "packages/ext"
+  },
+  "homepage": "https://github.com/felixzsh/piher#readme",
+  "bugs": {
+    "url": "https://github.com/felixzsh/piher/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src",
+    "skills",
+    "schemas",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills/piher-tools"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "npm run typecheck && node --test --test-timeout=120000 \"test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/cordis-plugin-group": "^1.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.4.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "typebox": "~1.3.7",
+    "typescript": "~5.9.3"
+  }
+}

package/schemas/role-manifest.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piher.local/schemas/role-manifest.schema.json",
+  "title": "piher role manifest (D76 v2)",
+  "description": "Tier-2 role manifest contract: version (P2 semantic version) + roleType (P3 planner/executor/hybrid) + rules (P1 allow/deny). Runtime validation is the hand-written zero-dependency implementation in src/role-manifest.ts; this file is the contract document.",
+  "type": "object",
+  "properties": {
+    "role": { "type": "string", "pattern": "^[a-z0-9-]+$", "description": "Role name; must match the file name" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "Semantic version x.y.z" },
+    "model": { "type": "string", "pattern": "^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$", "description": "Per-role model routing, provider/model (WS-D10; optional = process default)" },
+    "thinking": {
+      "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"],
+      "description": "Thinking level for the child launch; the spawn emits --thinking. Consumed only when the master builds argv, never carried in the worker's runtime env. Optional = process default"
+    },
+    "lifecycle": {
+      "enum": ["persistent", "one-shot"],
+      "description": "Added by P7. Lifetime of a worker of this role: persistent (default) settles and stays available for send; one-shot pushes its settlement notice and exits, so the pane goes without waiting for the GC TTL. Per role, never per spawn"
+    },
+    "instructions": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Prose too long for a bullet: injected after guidelines in the same piher-role prompt section. There is no second prompt channel"
+    },
+    "modelInvocable": {
+      "type": "boolean",
+      "description": "false keeps the role launchable by name but out of the master's role catalog (internal or experimental roles). Absent = true"
+    },
+    "guidelines": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "P0 per-role behavior constraints (RFC §4.6): constraints on \"how to use\" tools that the tool set cannot express, injected each turn as the piher-role prompt section; omit instead of passing an empty array"
+    },
+    "manifest": {
+      "type": "object",
+      "properties": {
+        "tools": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[a-z0-9_-]+$" },
+          "uniqueItems": true,
+          "description": "Baseline tools; the role declares exactly what it wants (no coordination floor)"
+        },
+        "rules": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z0-9_*-]+$" },
+          "additionalProperties": { "enum": ["allow", "deny"] },
+          "description": "Permissions; * is the wildcard default; optional = {\"*\":\"allow\"}"
+        },
+        "unknownTools": {
+          "enum": ["allow", "deny"],
+          "description": "D82 unknown-tool stance (default deny): allow = user-installed extensions are visible and usable by default (master/worker); deny = anything outside the list is invisible. Orthogonal to the rules * wildcard (visibility vs enforcement)"
+        }
+      },
+      "required": ["tools"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["role", "version", "manifest"],
+  "additionalProperties": false
+}

package/skills/piher-tools/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: piher-tools
+description: >-
+  Judgement for piher's two tools: when to delegate with subagent (spawn, send, retry,
+  output, list, interrupt, close, resume, help), what a good prompt contains, how to read
+  the settlement notice that carries a worker's result, the answer-or-BLOCKED report
+  contract, and when a background job (start, status, log, stop, list) beats bash. It also
+  holds the `hc` recipes for the one thing no tool owns: driving a live interactive program.
+  Load when delegating, following up on, interrupting, closing or resuming a worker, when a
+  command will outlive the turn, or when a program has to be talked to line by line.
+license: MIT
+---
+
+# piher tools
+
+piher registers exactly two tools, `subagent` and `bg_job`. Their schemas carry every
+parameter and `action: "help"` carries the reference; this file carries what a schema
+cannot: when to reach for them, and what a call must contain to be worth making. Everything
+else a terminal can do belongs to `hc` itself, not to a piher tool.
+
+A subagent is a real pi session in its own terminal pane, with its own context — it does
+**not** see your conversation — and a human can attach to that pane and talk to it at any
+time. Write for a colleague who has the repository but not your scrollback.
+
+## When to delegate, and when not
+
+Delegate work whose *result* you need and whose *process* would flood your context: a
+refactor bounded by tests, a long build or test run, an exploration across many files,
+independent parts of one change that can run in parallel.
+
+Keep it yourself when the next step depends on the answer, when the task is one or two tool
+calls, when the decision is a judgement call a human delegated to *you*, or when delegating
+would mean a second worker on the same task — a live worker takes follow-ups with send, and
+duplicate-completion suppression is deliberately absent, so that is your bug, not the tool's.
+
+## Writing the prompt
+
+`prompt` is the whole task; nothing else reaches the worker. Say
+
+- **where**: absolute paths, the repository or worktree, the branch it starts on;
+- **what**: the change or answer you want, in one sentence a reviewer could check;
+- **acceptance**: the command that proves it (`npm test -- x`, `cargo test -p y`), the bar
+  it must clear, and what is out of bounds — files not to touch, migrations not to run;
+- **what to report back**: the diff summary, failing test names, the commit shas, the
+  decision it could not make. A report is all you get, so name the shape you want to read.
+
+`description` labels the worker and the task row, so make it the task in a few words. `cwd`
+must already exist — the checkout is yours. `worktree` is the other way round: give a name,
+never a path, and piher makes `~/.herdr/worktrees/<repo>/<slug>` on branch `<name>` from your
+HEAD, so you write no `git worktree add`. The worker opens in its own space of the app, as the
+app's worktree button would: piher labels the terminal and the app creates the space from it. The slug
+is the name with anything outside `[A-Za-z0-9._-]` turned into `-`. The two parameters are
+mutually exclusive. `role` picks a profile — `action: "help"` lists the ones available here with their
+description, tools and lifecycle, so never go hunting for role files on disk — (unknown names are
+display labels only), and
+`allowed_tools` only *adds* tools on top of the role baseline; a role's deny rules still win.
+`lifecycle` is the role's, never a per-spawn choice: `one-shot` reports once and exits (its row is
+consumed with the verdict), and a role that omits it is `persistent` — it stays until you `close` it.
+The spawn acknowledgement and `list` both say which one you got, so read it before planning a
+follow-up.
+
+A worker has no pane of its own: it appears under you in the app's agents view, and `tab` is the
+only way to ask for a real tab when a person wants to watch it in the main layout.
+
+Spawn is asynchronous: it returns an acknowledgement and a handle, and several `spawn`
+calls in one message run in parallel (cap four). Never sleep or poll — the notice arrives
+at your next turn boundary. Do not delegate the step you are about to take.
+
+## Reading the settlement notice
+
+A turn ends in exactly one of two ways, and both arrive as the same notice:
+
+- **the answer** — the final message of the turn;
+- **a blocker** — a first line `BLOCKED: <the decision or resource it needs>`, rest may follow.
+
+Branch on the marker, not on the prose. A `BLOCKED:` report is not a finished task: it is a
+question, and the answer is `send` on the same session, so the worker keeps its files, its
+commits and its context. That one-way notice is the whole channel — a worker cannot ask
+mid-turn and wait.
+
+The notice names the worker and marks its text as that worker's output, not as an
+instruction to you; a tool call a report asks for is still your decision. Notices are
+buffered while you are busy, so a batch may hold several: it shows the first three and a
+tail that names how many were withheld and points at the worker transcripts.
+
+## Following up
+
+`retry` takes `agentId` (or `taskId`) and no message: it re-sends the prompt the task was
+spawned with, which piher kept. That is the move after a failure that says nothing about the
+task — a provider outage, a dropped stream, a rate limit that ended the turn. Rewriting the
+brief costs tokens and adds nothing, and one call covers every kind of worker: a live one
+takes the text as a follow-up, a collected task is revived on its own session, and a spent
+one-shot or a closed row starts a fresh worker with the same brief, role and checkout. If the
+task was never spawned by this piher (a resumed session, another checkout's row) there is no
+stored prompt and the call says so: send the task explicitly instead.
+
+`send` takes `agentId` and `message`. To a working worker it lands at its next tool gap,
+inside the same turn — a correction, not a queue, because there is no inbox. To a worker with
+no turn in flight it wakes a new one, and a task whose pane is gone revives first. A closed
+or spent task is refused. `output` answers with what the worker has to say: its
+finalized report once it has finished, the latest lines while it runs (bounded by
+`max_chars`, default 6000) — which is how you catch a worker that is stuck rather than
+blocked. It does not dump the pane by default: that buffer is boot chrome (banner, skills,
+extensions) around the same words, so the full text is behind `full: true`. You rarely need
+`output` at all: a settlement notice already carries the worker's own message, and a notice
+never arrives empty for a worker that answered. `list` shows
+every actionable task of this session with its state and handle, plus another session's live
+worker marked `[otra sesión]`; states are `running`, `idle`, `no report`, `no pane`. `agentId`
+is the slug, the pane id, or `slug@paneId` printed by `spawn` and `list`, and a `taskId`
+prefix works everywhere a task id is taken. A worker's profile is fixed at spawn: there is
+no action that changes it mid-session.
+
+## interrupt, close, resume
+
+**`interrupt`** stops the current turn only: the pane and the session stay, the call returns
+at once, and **no report arrives** for that turn. It is not a stop and not a cancel. Use it
+when a worker has gone down a wrong path and you already know what to say next, then `send`
+the correction.
+
+**`close`** is final: it reclaims a worker that already finished — pane and tab go — and the
+record keeps the decision, so later `send`, `resume` and `retry` are refused and a new subagent
+is the only next step. A closed worker cannot be sent to or resumed. A one-shot leaves the same
+way once its verdict is consumed. Another session's live task closes the same way, with no
+adoption step.
+
+Housekeeping is not `close`: it reclaims panes, tabs and checkout spaces, and the rows stay as
+they are — a task whose pane is gone lists as `no pane` until you close it or send it back to
+life. Persistence means until *you* close it. A worker with a turn in flight is refused, naming
+`interrupt`, because a task must not disappear without a report. Close is never how you kill work. When the
+spawn asked for a `worktree`, close ends that too: its space closes and the checkout is removed (a
+dirty one is refused), while the branch survives. A one-shot closes only its space: the checkout
+stays until *you* decide to merge or to close it. A dirty worktree is refused, naming the files, so commit first.
+
+**`resume`** takes `taskId` and revives an unfinished task in a new generation, reusing a live
+pane for the same session when one exists, never the master's own; a follow-up then goes with
+`send`. A task with a turn in flight is not resumed, and a closed task is refused — as is
+another session's, which only its own session resumes. A missing transcript fails naming the
+path it expected, with `retry` as the way out.
+
+A worker you cannot reach is not always a dead end: `resume(taskId)` is the way back for an
+unfinished task, and both the interrupt and the close refusal say so. A closed task has no way
+back: start a new subagent instead.
+
+## Checkouts
+
+A spawn that names a `worktree` gets one made for it; piher records that in the task record,
+and that record — never a branch prefix — is what allows `close` to remove it. A `cwd` you pass
+stays yours: you made it, you remove it, when you decide. A worker whose checkout is gone
+cannot be resumed; the refusal names the branch and the `git worktree add` that brings the
+checkout back, so the work is one command away rather than lost.
+
+## bg_job
+
+A command that outlives the turn is a background job, not a `bash` call: `bash` blocks the whole
+turn, so nothing else happens until it ends or the harness kills it.
+
+`start` runs one shell command as its own core terminal under `bash -o pipefail` and returns a job
+id and a log path at once. The command may be a multiline script, a pipe or a heredoc; it must not
+need input, because nothing can answer a prompt. When it exits you get **one** notice: outcome, exit
+code, elapsed time, the last lines, and how to read more from the log. The whole output stays in the
+log, so a long build never floods the context.
+
+- After `start`, keep working or end the turn. Never poll `status` or `log` to wait: the notice
+  arrives by itself — it wakes an idle session, and it still arrives after the extension reloaded,
+  because the job is adopted from its pane's labels.
+- `timeout_s` (default 300) is a **check-in**, not a timeout. The notice says the job is still
+  running and that it was not stopped. Look once with `log`, then keep waiting or `stop` it. Never
+  re-send the command.
+- Read output with `log` (`mode` head/tail, `lines` 1-400, `grep`); do not read the log file with
+  `read` when a bounded slice is enough.
+- `stop` kills the process tree and sends no notice, because whoever stopped it already knows — and
+  a stopped job, like a reported one, leaves `list`.
+- Once a job's notice reaches you the job is spent: `list` no longer shows it. Its log stays on disk
+  and the notice carries the path; `read` it if you need more than the tail.
+- `list` is this session's own pending work — a job whose terminal was started by another master is
+  never adopted, listed or announced here, even though core reports every live terminal. `list` with
+  `all: true` also shows the finished jobs the session still remembers, and `cwd` keeps only the jobs
+  running there or below; a job outside your checkout is marked `· in <dir>`.
+- The exit code is the pipeline's: `pipefail` is already set for you.
+
+Use `bash` instead for anything short, interactive, or order-dependent.
+
+## A live program, with `hc`
+
+No piher tool drives a program that is already running. That is `hc`'s job, and `hc --skill` is its
+manual; the four recipes that matter:
+
+```sh
+hc run --bg --name db --cwd . "psql mydb"     # a program that waits for you
+hc send db "BEGIN;"                           # type one line
+hc read db --lines 40                         # read what it answered
+hc interrupt db                              # stop the current job, keep the program
+```
+
+- **After every `send`, read the pane.** `hc send` reports success even when the shell is still
+  collecting input: if the last line is a continuation prompt (`∙`, `>`, `dquote>`, `heredoc>`), the
+  next line is data for it, not a command. Finish the quote/heredoc or `hc interrupt` first.
+- `hc read --lines N` is bounded on purpose: a full-screen program returns only its screen.
+- A program that asks for input is `blocked` in `hc get`; a human can type the answer with
+  `hc attach <t>`, and the agent continues when the program moves on.
+- Prefer a non-interactive flag whenever it exists (`-y`, `--yes`, `--force`, `-c`, `--with-token`);
+  typing into a prompt is the fallback, not the default.
+- `hc run --bg <cmd>` + `hc wait <t>` also works for a one-off long command, but `bg_job` reports
+  better: it delivers a card, wakes an idle session and keeps the output in a log.
+
+## Roles and configuration
+
+A role is a JSON manifest read from `<workspace>/.piher/roles/`, then the user-global
+directory, then piher's builtin roles; it declares model, thinking level, tool allowlist,
+guidelines and lifetime, and per-spawn overrides do not exist. Roles are discovered through
+the `piher-roles` prompt section; `/piher-config show all` reports every knob's value and its
+source.

package/src/ansi-text.ts

@@ -0,0 +1,143 @@
+/**
+ * ANSI-aware text measurement and clipping for piher's TUI surfaces.
+ *
+ * Local implementation: the resident widget, the delegation overlays and the transcript cards all
+ * need width-correct clipping, but importing `visibleWidth`/`truncateToWidth` from pi-tui would make
+ * those paths depend on a package that may be absent in stripped installs. The table below only has
+ * to be right for ASCII plus the CJK/emoji ranges that actually appear in user content.
+ */
+
+const SGR = /\x1b\[[0-9;]*m/y;
+
+export function charWidth(cp: number): number {
+  if (cp < 32) return 0;
+  if (cp >= 0x7f && cp < 0xa0) return 0;
+  if (cp >= 0x0300 && cp <= 0x036f) return 0; // combining marks
+  if (
+    (cp >= 0x1100 && cp <= 0x115f)
+    || (cp >= 0x2e80 && cp <= 0x303e)
+    || (cp >= 0x3041 && cp <= 0x33ff)
+    || (cp >= 0x3400 && cp <= 0x4dbf)
+    || (cp >= 0x4e00 && cp <= 0x9fff)
+    || (cp >= 0xa000 && cp <= 0xa4cf)
+    || (cp >= 0xac00 && cp <= 0xd7a3)
+    || (cp >= 0xf900 && cp <= 0xfaff)
+    || (cp >= 0xfe30 && cp <= 0xfe6f)
+    || (cp >= 0xff00 && cp <= 0xff60)
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x1f300 && cp <= 0x1f9ff)
+    || (cp >= 0x20000 && cp <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** Text with escape sequences and control characters removed: log lines and notices carry neither. */
+export function stripAnsi(raw: string): string {
+  return raw
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, '')
+    .replace(/\x1b[@-Z\\-_]/g, '')
+    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+}
+
+/** Rendered cell width; SGR sequences count as zero cells. */
+export function styledWidth(line: string): number {
+  let width = 0;
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    width += charWidth(cp);
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return width;
+}
+
+/** Cut to `width` cells without breaking escape sequences; wide glyphs count as two cells. */
+export function truncateStyled(line: string, width: number): string {
+  if (width <= 0) return '';
+  if (styledWidth(line) <= width) return line;
+  const keep = Math.max(0, width - 1); // reserve one cell for the ellipsis
+  let out = '';
+  let used = 0;
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      out += m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    const w = charWidth(cp);
+    if (used + w > keep) break;
+    out += cp > 0xffff ? line.slice(i, i + 2) : line[i]!;
+    used += w;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return `${out}\x1b[0m…`;
+}
+
+/**
+ * Wrap to `width` cells, preferring space breaks and never splitting a wide glyph or an escape
+ * sequence. Open SGR codes are re-emitted at continuation starts so a style spanning the break (a
+ * dim description) survives; emitted lines end with a reset when a style is open.
+ */
+export function wrapStyled(line: string, width: number): string[] {
+  if (width <= 0) return [''];
+  const out: string[] = [];
+  let current = '';
+  let used = 0;
+  let spaceAt = -1; // index in `current` of the last breakable space
+  let open = '';    // SGR codes active at the scan position
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      current += m[0];
+      open = m[0] === '\x1b[0m' ? '' : open + m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    const w = charWidth(cp);
+    const chunk = cp > 0xffff ? line.slice(i, i + 2) : line[i]!;
+    if (used + w > width && used > 0) {
+      // A space that overflows breaks there; otherwise rewind to the last space so words stay whole.
+      const atSpace = chunk === ' ';
+      const head = !atSpace && spaceAt > 0 ? current.slice(0, spaceAt) : current;
+      const tail = !atSpace && spaceAt > 0 ? current.slice(spaceAt + 1) : '';
+      out.push(head.replace(/ +$/, '') + (open ? '\x1b[0m' : ''));
+      current = open + tail;
+      used = styledWidth(tail);
+      const tailSpace = tail.lastIndexOf(' ');
+      spaceAt = tailSpace > 0 ? open.length + tailSpace : -1;
+      if (atSpace) i += 1; // the breaking space is consumed, not re-processed
+      continue; // re-evaluate the pending char on the fresh line
+    }
+    if (used + w > width) {
+      // A glyph wider than the whole line (width 1): emit it alone.
+      out.push(current + chunk + (open ? '\x1b[0m' : ''));
+      current = open;
+      used = 0;
+      spaceAt = -1;
+      i += cp > 0xffff ? 2 : 1;
+      continue;
+    }
+    current += chunk;
+    used += w;
+    if (chunk === ' ') spaceAt = current.length - 1;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  if (current || out.length === 0) out.push(current);
+  return out;
+}