janissary 0.5.0 → 0.5.2

package/ai/tasks/remove-deadcode.md

@@ -0,0 +1,206 @@
+# Remove Dead Code (clear all findings in one pass)
+
+Your job: run Knip, delete the dead code it reports, then prove the project is still green. Dead-code removal is mechanical — you only ever **delete code that nothing uses**, never add or rewrite logic. Clear all the safe findings in one pass.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+The rule is simple: **the compiler, the linter, and the tests must be green before you start and green again after you finish.** If the project is not green before you start, stop and tell the user. If you cannot keep it green, put the code back.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. Only stop early if the project isn't green before you start, or if you cannot keep it green after a removal (put the code back and report instead of pausing).
+
+## The one safety rule (read this first)
+
+There are two kinds of finding: **remove automatically** and **leave alone**.
+
+### Remove automatically — never ask
+
+You may remove these four kinds of finding on your own, start to finish, without stopping. Do **not** ask "Do you want me to proceed?". Do **not** wait for confirmation. Asking permission for safe removals is a mistake.
+
+- **Unused dependency / devDependency** — remove the package from `package.json`.
+- **Unused file** — delete the file (nothing imports it).
+- **Unused export** — delete the whole declaration.
+- **Unused exported type** — delete the whole type/interface.
+
+### Leave alone — skip it and list it (do NOT remove)
+
+Do **not** remove a finding if it is any of these. Just leave it in place and list it in your report. You never need to stop and ask in this task — skipping a piece of dead code is always safe.
+
+- A finding in **`src/controller.ts`** (the biggest, riskiest file).
+- A finding in **security, password/crypto, shell-execution, PTY/terminal, or network/browser** code.
+- A finding you could only remove by **editing a test file** (`*.test.ts`, `*.test.tsx`).
+- A finding whose removal looks like it would touch **more than 5 files**.
+- A name you can see is used in a **non-obvious way** — referenced as a string, via dynamic `import()`, or by something outside this repo.
+
+### Guardrails
+
+- **Do NOT run `knip --fix`.** It removes everything it finds and ignores the "leave alone" list above. Remove findings by hand.
+- **Act only on the four "unused" categories above.** If Knip prints any other kind of finding (`Unlisted dependencies`, `Unresolved imports`, `Duplicate exports`, `Unused class members`, …), do not touch it — just list it under "Other" in your report.
+- Never edit `knip.json`, `tsconfig.json`, `eslint.config.mjs`, or `package.json` (except to remove an unused-dependency line). Never add `// @public` tags or `ignore` entries to silence a finding.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — See the starting state (run these, write the numbers down)
+
+```bash
+npx tsc --noEmit 2>&1
+npm test 2>&1
+npm run lint 2>&1
+npm run knip 2>&1
+```
+
+The first three must all be **green** before you touch anything:
+
+- **Compiler (`npx tsc --noEmit`):** must finish with **no errors**.
+- **Tests (`npm test`):** **every** test must pass.
+- **Lint (`npm run lint`):** must report **no errors**. (Warnings are fine and do not count as red — the line `✖ 16 problems (0 errors, 16 warnings)` is green because errors is 0.)
+
+**If any of those three is not green, STOP and tell the user. Do not remove dead code on a project that is not already green** — fixing a pre-existing failure is not your job here.
+
+- **Knip (`npm run knip`):** this is your to-do list of findings. **If Knip reports no findings, there is nothing to do — report "No dead code found" and stop.**
+
+Always run these fresh; do not trust earlier output in the conversation.
+
+---
+
+## Step 2 — Read the Knip findings
+
+Knip groups findings under headers, like this:
+
+```
+Unused files (1)
+src/old-feature.ts
+
+Unused dependencies (1)
+some-package  package.json
+
+Unused exports (2)
+helperFn  function  src/utils.ts:12:17
+CONSTANT  unknown   src/config.ts:5:14
+
+Unused exported types (1)
+OldType  type  src/types.ts:42:13
+```
+
+For each finding note the **category**, the **file path**, and (for exports/types) the **line number**.
+
+Two facts about how Knip is set up here:
+
+- Because of the `ignoreExportsUsedInFile` setting, **every "unused export" Knip lists is used nowhere at all** — not in other files and not even in its own file. So the fix is always to **delete the entire declaration**, never just the `export` keyword.
+- Test files already count as usage. If a test imports something, Knip will **not** list it — so you do not need to grep test files yourself.
+
+---
+
+## Step 3 — Decide what to remove
+
+Go through every finding from Step 2 and sort it:
+
+- If it is one of the four removable categories **and** none of the "leave alone" conditions apply → it goes on your **removal list**.
+- Otherwise → it goes on your **skip list** (you will name these in the report, but not touch them).
+
+You do not need to ask anyone. Just build the two lists and continue.
+
+---
+
+## Step 4 — Back up, then remove (safest first)
+
+**Back up every file you will edit or delete** so you can restore it exactly:
+
+```bash
+cp src/foo.ts src/foo.ts.bak
+```
+
+Work through your removal list in this order:
+
+### 1. Unused dependency / devDependency
+
+Back up both lock and manifest first, because this also rewrites them:
+
+```bash
+cp package.json package.json.bak
+cp package-lock.json package-lock.json.bak
+```
+
+Remove the one line for that package from `package.json`, then:
+
+```bash
+npm install
+```
+
+(To undo later: copy both `.bak` files back, then run `npm install` again.)
+
+### 2. Unused file
+
+Back it up, then delete it:
+
+```bash
+cp src/old-feature.ts src/old-feature.ts.bak
+rm src/old-feature.ts
+```
+
+(First make sure the file is not named in a `package.json` script or in `bin` — if it is, skip it.)
+
+### 3. Unused export / unused exported type
+
+Open the file at the line Knip gave you and **delete the whole declaration** — the entire `function` / `const` / `type` / `interface`, from its first line to its closing brace.
+
+- If the finding is a **re-export line** (`export { X } from './y.js'` or `export type { X } from './y.js'`), just delete that line (or only the one name, if the line lists several).
+- Keep the diff minimal — do not reformat or tidy unrelated lines.
+
+Do not chase down unused imports by hand right now — the linter in Step 5 will list any import that became unused, and you will delete those then.
+
+---
+
+## Step 5 — Verify (run in this order; everything must be green)
+
+```bash
+npx tsc --noEmit 2>&1
+npm run lint 2>&1
+npm test 2>&1
+npm run knip 2>&1
+```
+
+Each command checks one thing. Fix or restore before moving on.
+
+1. **Compiler — green (no errors).** An error like `Cannot find name 'X'` or `has no exported member 'X'`, naming something you removed, means it was **not** dead — a reference still exists. **Restore that finding's backup**, move it to your skip list, and re-run.
+2. **Lint — green (no errors).** A new error is almost always an **import that became unused** after you deleted a declaration. The linter prints its file and line — delete that import line, then re-run. Never silence anything with an `eslint-disable` comment.
+3. **Tests — green (all pass).** If a test now fails, something you removed was used in a way the compiler could not see. **Restore that finding's backup**, skip it, and re-run. Never edit a test to make it pass.
+4. **Knip — the findings you removed are gone.** Re-running Knip should no longer list anything you removed. (Findings you deliberately skipped will still be listed — that is expected; they go in your report.)
+
+The compiler, the linter, and the tests must all end **green**, exactly as they were in Step 1. When they are, **delete the backup files**: `rm *.bak src/**/*.bak` (and `package-lock.json.bak` if you made one).
+
+---
+
+## Step 6 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Removed:
+  Dependencies:   <packages removed, or "none">
+  Files:          <files deleted, or "none">
+  Exports/types:  <count> removed, in <files>
+
+Skipped (left in place): <findings you did not touch + one-word reason each, or "none">
+Other Knip findings:     <non-"unused" findings, or "none">
+
+Compiler:  green / <errors, if any>
+Lint:      green / <errors, if any>
+Tests:     green / <what failed>
+Knip:      <N findings before> -> <N remaining (all deliberately skipped)>
+```
+
+Keep it brief. Done.

package/ai/tasks/remove-duplication.md

@@ -0,0 +1,202 @@
+# Remove Code Duplication (one clone per run)
+
+Your job: remove **one** duplicated block of code, then prove nothing broke. Do exactly one clone, then verify.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+Deduplication edits real code that other files may import, so the rule is simple: **the tests must pass before you start and still pass after. If you cannot keep them passing, put the code back the way it was.**
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. Only stop early if the project isn't green before you start (Step 1), or if every remaining candidate clone is blocked (see "Blocked work" below).
+
+## What you may and may not do
+
+### Safe work — DO IT AUTOMATICALLY, never ask
+
+When your plan is **only** safe work, you **must carry it out yourself, start to finish, without stopping.** Do **not** ask "Do you want me to proceed?". Do **not** pause to show the plan for approval. Do **not** wait for confirmation. Just make the change and verify it.
+
+Safe work is exactly these three fixes (and nothing else), each done by its Recipe in Step 5:
+
+- **Recipe 1 — within-file** (preferred, safest): two blocks in the **same** file → one local helper in that same file. No other file changes.
+- **Recipe 2 — move to the owner file**: the shared block clearly belongs to one of the two files (e.g. formatting logic → `state-format.ts`); put it there and import it at the other site. Two files change.
+- **Recipe 3 — new shared file**: neither file owns it → put the shared block in a new `src/<name>.ts` and import it at both sites. Three files change (the new file + the two sites).
+
+Adding a **new** function (even an exported one) is safe. Renaming or removing an **existing** export is not (see below).
+
+### Blocked work — skip and pick a different clone
+
+If removing the clone would require any of the following, **go back to Step 3** and pick the next clone instead. Never ask the user — just skip and move on.
+
+1. Renaming, removing, or changing the arguments of an **existing** `export` (other files import it).
+2. Editing **more than 3 files** in total.
+3. Touching **`src/controller.ts`** (the biggest, riskiest file — its clones are high-value but not for an unattended run).
+4. A helper that would be shared **between `src/` and `web/src/`** (that needs a build change).
+5. Editing **any test file** (`*.test.ts`, `*.test.tsx`).
+6. Touching **security, password/crypto, shell-execution, PTY/terminal, or network/browser** code.
+
+If every remaining clone is blocked, list each one and why it was blocked in your report, and stop without changing any code.
+
+> You may edit **only** the clone-site files, plus (optionally) **one** new helper file you create. Never edit `.jscpd.json`, `fta.json`, `eslint.config.mjs`, `package.json`, `tsconfig.json`, any other config file, or any test file. Leave the `threshold` in `.jscpd.json` alone.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — See the starting state (run these, write the numbers down)
+
+Run all three and read the output:
+
+```bash
+npm test 2>&1
+npm run lint 2>&1
+npm run duplication 2>&1
+```
+
+Record these starting numbers — you will compare against them at the end. Put them straight into your report draft (Step 7):
+
+- **Tests:** they must be **green** (all passing). If any test is already failing **before** you touch anything, STOP and tell the user — do not start on a broken suite.
+- **Lint:** near the end of `npm run lint` is a line like `✖ 16 problems (0 errors, 16 warnings)`. Write down the **errors** and **warnings** counts.
+- **Duplication:** near the end of `npm run duplication` is a line `Found N clones.` — write down **N**. The table just above it has a `Total:` row; in its `Duplicated lines` column is a percentage like `152 (2.47%)` — write down that **%**. (Ignore the promotional lines at the very bottom.)
+
+Always run these fresh. Do not trust earlier output in the conversation.
+
+---
+
+## Step 2 — Read the clone list
+
+`npm run duplication` prints each clone as two lines, like this:
+
+```
+Clone found (typescript)
+ - commands/state.ts [11:64 - 34:58]
+   state-format.ts [4:57 - 24:115]
+```
+
+Reading it:
+
+- The two lines are the **two copies** of the same code: file, then `[startLine:startCol - endLine:endCol]`.
+- **Same file name on both lines = a within-file clone** (Recipe 1, the safest). Two different files = a cross-file clone.
+- **Clone size in lines ≈ `endLine − startLine`** (jscpd does not print it). The two sides may differ by a line or two; use the bigger number. You only need this for ranking, so a rough count is fine.
+- **Path gotcha:** jscpd drops the scan-root prefix. A path like `messaging.ts` is really **`src/messaging.ts`**, and `commands/state.ts` is **`src/commands/state.ts`**. If a file is not under `src/`, it is under `web/src/`. When in doubt, search for the file by name before editing.
+
+---
+
+## Step 3 — Pick exactly one clone to remove
+
+1. List every clone from Step 2.
+2. **Cross out** any clone where **either** side is:
+   - a `*.test.ts` / `*.test.tsx` file,
+   - `src/main.ts`,
+   - `src/controller.ts`,
+   - `src/pty.ts`, `src/shell.ts`, or any file whose main job is spawning processes, running a terminal, doing network, or driving a browser,
+   - and cross out any clone whose two sides are split across `src/` and `web/src/`.
+3. From what remains, pick **one**, in this order:
+   1. **Any within-file clone** (same file on both lines) — pick the largest of these. These are the safest.
+   2. If there are no within-file clones left, pick the **largest cross-file clone**.
+4. Open both sides and read the duplicated code. If removing it cleanly would require renaming/removing an existing `export`, or editing more than 3 files → it is needs-permission (rules 1–2); cross it out and pick the next one.
+
+State your pick in one sentence: both file paths (with the real `src/` prefix), the line ranges, the rough size, and whether it is within-file or cross-file.
+
+---
+
+## Step 4 — Plan the fix (a quick note to yourself, then keep going)
+
+Jot a one- or two-line plan: the name of the helper you will create and which file it lives in, and what each clone site becomes (a call to the helper). This is a note for **you**, not a message to send — do **not** post it and wait for a reply.
+
+Check the plan against **What you may and may not do**:
+
+- If any of points 1–6 applies → go back to Step 3 and pick a different clone.
+- Otherwise (all safe work) → go straight to Step 5 and make the change **now, on your own, without asking.**
+
+---
+
+## Step 5 — Make the change
+
+**First, back up every file you are about to edit**, so you can restore it exactly if anything goes wrong:
+
+```bash
+cp src/foo.ts src/foo.ts.bak
+```
+
+Then apply the Recipe that matches your clone. Keep the diff as small as possible — do not reformat or "tidy" unrelated lines.
+
+### Recipe 1 — within-file (same file on both lines)
+
+1. Confirm both blocks are inside function bodies, not whole `export`ed declarations.
+2. Add a new helper function (not exported) **below** the second block in the same file. Give it the values the block needs as parameters; have it `return` what the block produced.
+3. Replace **both** blocks with a call to the helper.
+4. Nothing else changes — no new imports, no other files.
+
+### Recipe 2 — move the block into the file that owns it
+
+1. Decide which of the two files clearly owns the logic (e.g. formatting → `state-format.ts`).
+2. In that file, add a **new exported** helper (or reuse one that already does exactly this). Adding a new export is fine; do **not** rename or change an existing export.
+3. In the other file, import the helper and replace its block with a call.
+4. Only these two files change.
+
+### Recipe 3 — new shared file (only if neither file owns it)
+
+1. Create `src/<descriptive-name>.ts` with the shared function exported:
+   ```ts
+   export function sharedThing(/* params */) {
+     // the duplicated logic, once
+   }
+   ```
+2. At **each** clone site, import it and replace the block with a call:
+   ```ts
+   import { sharedThing } from './descriptive-name.js'; // .js on purpose
+   ```
+3. Only three files change (new file + the two sites).
+
+If you open the code and cannot see a clean way to extract it (for example the two ranges overlap, or the block depends on lots of surrounding variables), **do not force it** — restore your backup, go back to Step 3, and pick a different clone (or report that no safe fix was available).
+
+### Style
+
+- Match nearby naming: `camelCase` functions, `kebab-case` filenames.
+- Relative imports use a **`.js`** extension even though the source is `.ts` (`import { x } from './foo.js'`). A new helper file must follow this.
+- Add a comment only if the *why* is non-obvious; never one that just restates *what* the code does.
+
+---
+
+## Step 6 — Verify (run in this order; fix or put it back)
+
+```bash
+npm run lint 2>&1
+npm test 2>&1
+npm run duplication 2>&1
+```
+
+Check each, in order:
+
+1. **Lint is no worse.** Look at the `✖ … problems (… errors, … warnings)` line again. **Errors and warnings must each be the same as Step 1 or lower — never higher.** A new error after a dedup is almost always a missing `.js` import extension or an import left unused after you deleted a block — fix it in your source file. Never silence anything with an `eslint-disable` comment.
+2. **Tests pass.** If a test now fails, your change moved or renamed something a test relied on. Try the obvious fix in your source file (run lint first — a broken import shows up clearly there but as a confusing crash in tests). If it does not pass quickly, **restore your backups** (`cp src/foo.ts.bak src/foo.ts`, and delete any new file you created) and report what blocked you. Never edit a test to make it pass.
+3. **Duplication went down.** In the new `npm run duplication` output, **the clone you targeted must be gone**, and the `Total:` row percentage must be the same or lower than Step 1 — never higher. If your clone still appears, you updated only one of the two sides; fix the other.
+
+When all three pass, **delete the backup file(s)**: `rm src/foo.ts.bak`.
+
+---
+
+## Step 7 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Clone removed:  <file A> [lines] ↔ <file B> [lines]
+Fix:            <one sentence — e.g. "extracted buildTabState() into tab-state.ts">
+Duplication:    <before %> -> <after %>   (clones: <before N> -> <after N>)
+Lint:           <before E errors, W warnings> -> <after>
+Tests:          all pass / <what failed>
+```
+
+Keep it brief. Done.

package/ai/tasks/update-package.md

@@ -0,0 +1,137 @@
+# Update a Package (one package per run)
+
+Your job: update **one** npm package to the latest version its existing `package.json` range allows, fix any code that breaks, and prove the project is still green. Do exactly one package, then verify. Follow the steps **in order, exactly as written** — do not skip a step or combine steps.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Only stop early for the conditions explicitly listed below.
+
+The rule is simple: **the compiler, the linter, and the tests must be green before you start and green again after you finish.** If not green before you start, stop and tell the user. If you can't get it green again after two fix attempts, put the package back and stop.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — Confirm the project is green
+
+```bash
+npx tsc --noEmit 2>&1
+npm run lint 2>&1
+npm test 2>&1
+```
+
+All three must pass: compiler has no errors, lint has no errors (warnings are fine), every test passes.
+
+**If any of the three is not green, STOP and tell the user.** Do not proceed.
+
+---
+
+## Step 2 — List outdated packages
+
+```bash
+npm outdated 2>&1
+```
+
+A non-zero exit code here is normal and expected when it lists rows — it is not a failure.
+
+**If it prints nothing, report "No outdated packages found" and stop.**
+
+---
+
+## Step 3 — Pick one package (mechanical, no judgment needed)
+
+`npm outdated` prints a table with columns `Package`, `Current`, `Wanted`, `Latest`.
+
+1. Look only at rows where `Current` and `Wanted` are **different**. Ignore the `Latest` column entirely — you are never bumping the version range in `package.json` in this task, only updating within the range it already allows.
+2. Take the **first such row, top to bottom**. That is your package.
+3. If you already tried this exact package earlier in this run (see Step 6), skip it and take the next row instead.
+4. If no row has `Current` different from `Wanted` (every remaining row only differs in `Latest`), report "No in-range updates available" plus the full `npm outdated` output, and stop.
+
+State your pick in one line: `<package> <Current> -> <Wanted>`.
+
+---
+
+## Step 4 — Install the update
+
+Back up the manifest and lock file (this step rewrites both):
+
+```bash
+cp package.json package.json.bak
+cp package-lock.json package-lock.json.bak
+```
+
+Install:
+
+```bash
+npm update <package>
+```
+
+(`npm update` moves the package to `Wanted` without changing the version range in `package.json`.)
+
+---
+
+## Step 5 — Re-check, fix, repeat (max 2 attempts)
+
+Run:
+
+```bash
+npx tsc --noEmit 2>&1
+npm run lint 2>&1
+npm test 2>&1
+```
+
+**All three green →** delete the backups (`rm package.json.bak package-lock.json.bak`) and go to Step 7.
+
+**Not all green →** this is attempt 1 of at most 2:
+
+1. Read the compiler's error output first — it names the file, line, and the missing/changed symbol. That is almost always enough to know what to fix. Only look inside `node_modules/<package>` for the current type definitions if the compiler message alone isn't enough to tell you the new shape.
+2. Edit only the files the errors point at. Do not touch anything else.
+3. Re-run the three commands above.
+4. If still not green, make **one more** attempt (attempt 2 of 2), same process.
+5. If still not green after attempt 2, go to Step 6 (revert).
+
+If all three are green at any point in this loop, delete the backups and go to Step 7.
+
+---
+
+## Step 6 — Revert (only if Step 5 never went green)
+
+```bash
+cp package.json.bak package.json
+cp package-lock.json.bak package-lock.json
+npm install
+```
+
+If this is the **first** package you've reverted this run, go back to Step 3 and pick the next candidate. If this is the **second** package you've reverted this run, stop — report both packages tried and why each was reverted.
+
+---
+
+## Step 7 — Merge the change to master
+
+Execute `ai/tasks/merge-change-to-master.md` in full. That document owns the merge workflow — follow its steps without deviation. Use commit type `build`, unless the code fixes from Step 5 are large enough that `fix` describes the change better.
+
+---
+
+## Step 8 — Report
+
+```
+Package:       <name>  <old-version> -> <new-version>
+Code changes:  <files touched to fix API changes, or "none needed">
+Compiler:      green
+Lint:          green
+Tests:         green
+PR:            <url> (#<number>)
+Status:        merged
+```
+
+If you stopped early (nothing outdated, no in-range update available, or both attempts reverted), report that in one or two sentences plus the full `npm outdated` output. Keep it brief. Done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janissary",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "A terminal UI shell with built-in commands and shell execution",
   "bin": {
     "janus": "./bin/janus.mjs"
@@ -28,7 +28,7 @@
     "check:full": "npm run typecheck && npm run lint && npm run test && npm run lint:css && npm run quality && npm run duplication && npm run knip",
     "lint:files": "node scripts/lint-files.mjs",
     "format": "prettier --write .",
-    "postinstall": "chmod +x node_modules/node-pty/prebuilds/*/spawn-helper",
+    "postinstall": "node scripts/postinstall.mjs",
     "playwright:install-chromium": "npx playwright install chromium",
     "test:server": "vitest run --project server",
     "test:watch": "vitest --project server --project client",
@@ -79,11 +79,13 @@
     "@vitejs/plugin-vue": "^6.0.7"
   },
   "files": [
+    "ai",
     "bin",
     "dist",
     "chrome-extension",
     "agent-names.json",
-    "help.md"
+    "help.md",
+    "scripts"
   ],
   "type": "module",
   "dependencies": {

package/scripts/changed-files.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Detect changed files in the working tree (uncommitted + untracked).
+// Used by lint-files, check-diff, and other dev tools.
+
+import { execFileSync } from 'node:child_process';
+
+// eslint-disable-next-line unicorn/no-exports-in-scripts
+export function changedFiles() {
+  try {
+    // No explicit paths: everything not yet committed. `git diff HEAD` covers both
+    // staged and unstaged changes; `--diff-filter=d` drops deletions (can't lint a gone
+    // file); `ls-files --others --exclude-standard` adds new, non-ignored files.
+    const fromGit = (command, commandArguments) =>
+      execFileSync(command, commandArguments, { encoding: 'utf8' }).split('\n').filter(Boolean);
+    const changed = fromGit('git', ['diff', '--name-only', '--diff-filter=d', 'HEAD']);
+    const untracked = fromGit('git', ['ls-files', '--others', '--exclude-standard']);
+    return [...new Set([...changed, ...untracked])];
+  } catch {
+    // No git or no HEAD (fresh clone, initial commit): treat as no changes.
+    return [];
+  }
+}