@1outres/dsh-plugin-scratchpad 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1outres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# @1outres/dsh-plugin-scratchpad
 
-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.
+A place for work that belongs to no repository: one-off scripts, small
+experiments, research, writing. **New scratch** creates a new empty directory,
+registers it as its own workspace, and opens a session there. Archive the
+session when you are done and the directory is moved out of the way.
+
+Install just this plugin:
+
+```sh
+dsh plugin add @1outres/dsh-plugin-scratchpad
+```
+
+Or install it with every plugin in the repository through the
+[`@1outres/dsh-plugins`](../dsh-plugins) bundle. Enable one or the other: both
+insert the same `scratchpad` row.
+
+## Starting a scratch
+
+Any of these opens a scratch:
+
+- **New scratch** at the foot of the sidebar, beside Settings.
+- `/scratch` in the composer of any session.
+- **New scratch** in the New Session row of a blank session in the
+  `scratchpad` root workspace (see below).
+
+A new scratch is `~/.dsh/scratchpad/YYYY-MM-DD-HHmmss/`, named after the local
+time of the browser and suffixed `-2`, `-3`, ... only on a collision. The
+directory starts empty: no `git init`, no files. The workspace is titled after
+the directory; renaming the workspace or the session never renames the
+directory.
+
+When the newest scratch is still unused (nothing was sent in any of its
+sessions and none is archived), the button opens it again instead of creating
+another empty directory.
+
+Each scratch is its own workspace, so the session's file policy covers that
+directory only, and the Files panel, terminal and **New Session** in the
+workspace work as anywhere else.
+
+### The root workspace
+
+Creating a scratch also registers the root, `~/.dsh/scratchpad`, as a
+workspace. With **View options → Group by → Workspace Tree** in the sidebar's
+Workspaces header, every scratch nests under it, so the scratches read as one
+`scratchpad` project. The grouping choice is saved per browser and defaults to
+flat.
+
+**New Session** in the root workspace opens a session in the root itself. That
+session can write to every scratch, which suits work across scratches. Its
+New Session row shows a **New scratch** chip to start in a new scratch
+instead. Set `registerRoot: false` to stop registering the root.
+
+## Archiving a scratch
+
+When every session in a scratch is archived, the plugin:
+
+1. Waits until those sessions stop running anything: the turn, subagents,
+   background jobs, schedules and terminals. After two minutes it gives up and
+   leaves the directory where it is; the next Harness start tries again.
+2. Checks the sessions are still archived (the archive notice offers Undo).
+3. Moves the directory to `~/.dsh/scratchpad/.archived/<name>` and removes
+   the workspace from the sidebar. The archived sessions stay under
+   **Ungrouped**, hidden like any archived session.
+
+Unarchiving any of those sessions moves the directory back before the sidebar
+shows the session again, registers the workspace, and attaches its sessions.
+Forking an archived session does the same. A workspace restored this way
+starts at the top of the sidebar.
+
+Archiving a session in the root workspace moves nothing. Deleting a scratch
+workspace from the sidebar only removes the registration, as it does for any
+workspace; the plugin leaves that directory alone and does not register it
+again. Nothing is ever deleted: empty `.archived` entries stay until you
+remove them.
+
+The Host half catches up at startup with archives and unarchives made while it
+was off.
+
+## Settings
+
+Edit them on the plugin's settings page, or in the profile patch under the
+`scratchpad` row. Changing either restarts the Host half.
+
+| Field          | Default             | Meaning                                                            |
+| -------------- | ------------------- | ------------------------------------------------------------------ |
+| `root`         | `~/.dsh/scratchpad` | Directory that holds the scratches. `~` is the Host user's home.   |
+| `registerRoot` | `true`              | Register the root as a workspace too, for Workspace Tree grouping. |
+
+The root does not follow `$DSH_HOME`; set `root` when you moved the Harness
+home.
+
+## How it works
+
+1. The browser half creates the session with `sessions.create({ cwd })`. The
+   Host creates the directory with the session, which fixes the session's
+   working directory and file-policy root.
+2. The Host half sees the new Agent in `agent/created`, registers the root
+   and the scratch with `workspaceRegistry.create`, and attaches the session.
+   The browser waits for that workspace and opens it like any other.
+3. The Host half follows the registry's archive set through the storage
+   `domain/changed` event, which fires after each durable registry write and
+   before any browser hears of it. Archive moves wait in the background;
+   unarchive moves run synchronously inside the event.
+4. Every move is one `rename` inside the root. Files are never copied or
+   deleted.
+
+## Limits
+
+- **Deleting `~/.dsh` deletes the scratches too.** Set `root` elsewhere to
+  keep them apart from Harness data.
+- The archive bookkeeping reads Harness internals: the Workspace registry's
+  stored state (`archivedSessionIds`) through `domain/changed`, and the
+  `workspace/session-activity` check. A Harness update within
+  `>=0.2.1-rc.5 <0.3.0` can still change them; the move then stops happening
+  while creation keeps working.
+- Waiting for running work covers what the Harness reports. A persistent
+  shell, an MCP server or any process writing to an absolute path in the
+  scratch is not tracked, and can recreate files at the old path after the
+  move.
+- A restored scratch loses its position in the sidebar and its session order
+  is rebuilt newest first. A custom workspace title is reset to the directory
+  name.
+- The browser decides name collisions from the sessions and workspaces it
+  knows. A directory created by hand with the same name is reused as is.
+- A root reached through a symlink is matched by its canonical path on the
+  Host. In the browser, reusing the newest scratch and the root chip compare
+  the configured spelling only.
+- The built-in **New Session** of a scratch workspace opens a second session
+  in the same directory: the Harness offers no way to change it per workspace.
+- English only.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Installs this plugin on its own (dsh plugin add @1outres/dsh-plugin-scratchpad).
+# The @1outres/dsh-plugins bundle inserts the same "scratchpad" row, so select
+# one bundle or the other, never both.
+- insert:
+    - id: scratchpad
+      name: "@1outres/dsh-plugin-scratchpad"

package/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none" role="img" aria-labelledby="title">
+  <title id="title">Scratchpad</title>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#F2A33A"/>
+  <path d="M19 13H37L47 23V48C47 49.657 45.657 51 44 51H19C17.343 51 16 49.657 16 48V16C16 14.343 17.343 13 19 13Z" fill="#FFFFFF" fill-opacity="0.95"/>
+  <path d="M37 13V20C37 21.657 38.343 23 40 23H47" fill="#FBE3BD"/>
+  <path d="M37 13V20C37 21.657 38.343 23 40 23H47" stroke="#C97A12" stroke-width="2" stroke-linejoin="round"/>
+  <path d="M22 30H34M22 36H30" stroke="#E0A44E" stroke-width="2.4" stroke-linecap="round"/>
+  <circle cx="41" cy="42" r="8" fill="#C97A12"/>
+  <path d="M41 38V46M37 42H45" stroke="#FFFFFF" stroke-width="2.4" stroke-linecap="round"/>
+</svg>

package/lib/client.js

@@ -0,0 +1,502 @@
+/* Generated by scripts/build.mjs — do not edit. */
+window.__ModuleLoader__.load({
+	id: "@1outres/dsh-plugin-scratchpad",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		"use strict";
+		var __defProp = Object.defineProperty;
+		var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+		var __getOwnPropNames = Object.getOwnPropertyNames;
+		var __hasOwnProp = Object.prototype.hasOwnProperty;
+		var __export = (target, all) => {
+		  for (var name in all)
+		    __defProp(target, name, { get: all[name], enumerable: true });
+		};
+		var __copyProps = (to, from, except, desc) => {
+		  if (from && typeof from === "object" || typeof from === "function") {
+		    for (let key of __getOwnPropNames(from))
+		      if (!__hasOwnProp.call(to, key) && key !== except)
+		        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+		  }
+		  return to;
+		};
+		var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+		// src/client/index.tsx
+		var index_exports = {};
+		__export(index_exports, {
+		  COMMAND: () => COMMAND,
+		  FOOTER_SLOT: () => FOOTER_SLOT,
+		  HERO_SLOT: () => HERO_SLOT,
+		  NAMESPACE: () => NAMESPACE,
+		  apply: () => apply,
+		  inject: () => inject
+		});
+		module.exports = __toCommonJS(index_exports);
+
+		// src/shared/paths.ts
+		var DEFAULT_ROOT = "~/.dsh/scratchpad";
+		function trimTrailingSlashes(path) {
+		  let end = path.length;
+		  while (end > 1 && (path[end - 1] === "/" || path[end - 1] === "\\")) end--;
+		  return path.slice(0, end);
+		}
+		function expandHome(path, home) {
+		  const value = path.trim();
+		  if (value === "~" || value.startsWith("~/") || value.startsWith("~\\")) {
+		    if (home === void 0 || home === "") return void 0;
+		    return trimTrailingSlashes(`${trimTrailingSlashes(home)}${value.slice(1)}`);
+		  }
+		  return trimTrailingSlashes(value);
+		}
+		function isAbsolutePath(path) {
+		  return path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\");
+		}
+		function resolveRoot(configured, home) {
+		  const raw = configured === void 0 || configured.trim() === "" ? DEFAULT_ROOT : configured;
+		  const expanded = expandHome(raw, home);
+		  if (expanded === void 0 || !isAbsolutePath(expanded)) return void 0;
+		  return expanded;
+		}
+		function separatorOf(root) {
+		  return /^[A-Za-z]:\\/.test(root) || root.startsWith("\\\\") ? "\\" : "/";
+		}
+		function joinPath(dir, name) {
+		  const base = trimTrailingSlashes(dir);
+		  const sep = separatorOf(base);
+		  return base.endsWith(sep) ? `${base}${name}` : `${base}${sep}${name}`;
+		}
+		function splitPath(path) {
+		  const trimmed = trimTrailingSlashes(path);
+		  const at = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+		  if (at < 0) return { parent: "", name: trimmed };
+		  return {
+		    parent: at === 0 ? trimmed.slice(0, 1) : trimmed.slice(0, at),
+		    name: trimmed.slice(at + 1)
+		  };
+		}
+		function isScratchName(name) {
+		  return name !== "" && !name.startsWith(".") && !/[\\/]/.test(name);
+		}
+		function scratchNameOf(path, roots) {
+		  if (path === void 0) return void 0;
+		  const { parent, name } = splitPath(path);
+		  if (!isScratchName(name)) return void 0;
+		  return roots.some((root) => trimTrailingSlashes(root) === parent) ? name : void 0;
+		}
+		function isRootPath(path, roots) {
+		  if (path === void 0) return false;
+		  const value = trimTrailingSlashes(path);
+		  return roots.some((root) => trimTrailingSlashes(root) === value);
+		}
+		function pad(value) {
+		  return String(value).padStart(2, "0");
+		}
+		function scratchName(date) {
+		  return [
+		    date.getFullYear(),
+		    pad(date.getMonth() + 1),
+		    pad(date.getDate()),
+		    `${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+		  ].join("-");
+		}
+		function uniqueName(base, taken) {
+		  if (!taken(base)) return base;
+		  for (let n = 2; ; n++) {
+		    const candidate = `${base}-${n}`;
+		    if (!taken(candidate)) return candidate;
+		  }
+		}
+
+		// src/client/components.tsx
+		var import_react = require("react");
+
+		// src/client/icons.tsx
+		var import_jsx_runtime = require("react/jsx-runtime");
+		function IconScratch({ size = 16, className }) {
+		  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+		    "svg",
+		    {
+		      width: size,
+		      height: size,
+		      className,
+		      viewBox: "0 0 16 16",
+		      fill: "none",
+		      "aria-hidden": "true",
+		      children: [
+		        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+		          "path",
+		          {
+		            d: "M9.5 1.5H4A1.5 1.5 0 0 0 2.5 3v10A1.5 1.5 0 0 0 4 14.5h8a1.5 1.5 0 0 0 1.5-1.5V5.5l-4-4Z",
+		            stroke: "currentColor",
+		            strokeLinejoin: "round"
+		          }
+		        ),
+		        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M9.5 1.5v4h4", stroke: "currentColor", strokeLinejoin: "round" }),
+		        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("path", { d: "M8 7.5v5M5.5 10h5", stroke: "currentColor", strokeLinecap: "round" })
+		      ]
+		    }
+		  );
+		}
+
+		// src/client/components.tsx
+		var import_jsx_runtime2 = require("react/jsx-runtime");
+		function useObservable(observable) {
+		  const subscribe = (0, import_react.useCallback)(
+		    (listener) => observable.subscribe(listener),
+		    [observable]
+		  );
+		  const getSnapshot = (0, import_react.useCallback)(() => observable.getSnapshot(), [observable]);
+		  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+		}
+		function NewScratchFooterButton({ wide, t, start, status }) {
+		  const { busy, error } = useObservable(status);
+		  const label = busy ? t("action.busy") : error ?? t("action.label");
+		  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+		    "button",
+		    {
+		      type: "button",
+		      className: "dsh-scratch-footer",
+		      "data-rail": wide ? void 0 : "",
+		      disabled: busy,
+		      title: error ?? t("action.hint"),
+		      "aria-label": t("action.label"),
+		      onClick: () => {
+		        void start();
+		      },
+		      children: [
+		        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(IconScratch, { size: 16 }),
+		        wide ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "dsh-scratch-label", "data-error": error === void 0 ? void 0 : "", children: label }) : null
+		      ]
+		    }
+		  );
+		}
+		function NewScratchChip({ t, start, status, sessionId, sessions, isRoot }) {
+		  const list = useObservable(sessions);
+		  const { busy, error } = useObservable(status);
+		  if (!isRoot(list.byId[sessionId]?.cwd)) return null;
+		  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+		    "button",
+		    {
+		      type: "button",
+		      className: "dsh-scratch-chip",
+		      disabled: busy,
+		      title: error ?? t("chip.hint"),
+		      onClick: () => {
+		        void start();
+		      },
+		      children: [
+		        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(IconScratch, { size: 14 }),
+		        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: busy ? t("action.busy") : t("chip.label") })
+		      ]
+		    }
+		  );
+		}
+
+		// src/client/i18n.ts
+		var en = {
+		  "action.label": "New scratch",
+		  "action.hint": "Start a session in a new empty scratch directory",
+		  "action.busy": "Creating scratch\u2026",
+		  "chip.label": "New scratch",
+		  "chip.hint": "This session can write to every scratch. Start in a new empty scratch directory instead",
+		  "command.label": "New scratch",
+		  "command.description": "Start a session in a new empty scratch directory",
+		  "error.root": "The scratch root is not an absolute path, or the Host is not connected yet",
+		  "error.create": "Could not create the scratch: {detail}"
+		};
+
+		// src/client/scratch.ts
+		var REGISTER_TIMEOUT_MS = 15e3;
+		var ERROR_HOLD_MS = 6e3;
+		var ScratchRootError = class extends Error {
+		  constructor() {
+		    super("scratch root unavailable");
+		    this.name = "ScratchRootError";
+		  }
+		};
+		function scratchWorkspaces(snapshot, roots) {
+		  return snapshot.items.filter((workspace) => scratchNameOf(workspace.path, roots) !== void 0).sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt));
+		}
+		function reusableScratch(workspaces, sessions, roots) {
+		  const [latest] = scratchWorkspaces(workspaces, roots);
+		  if (latest === void 0) return void 0;
+		  const archived = new Set(workspaces.archivedSessionIds);
+		  const unused = latest.sessionIds.every(
+		    (id) => !archived.has(id) && sessions.byId[id]?.blank === true
+		  );
+		  return unused ? latest : void 0;
+		}
+		function nameTaken(name, workspaces, sessions, roots) {
+		  if (workspaces.items.some((workspace) => scratchNameOf(workspace.path, roots) === name)) {
+		    return true;
+		  }
+		  return Object.values(sessions.byId).some((row) => scratchNameOf(row?.cwd, roots) === name);
+		}
+		async function startScratch(deps) {
+		  const root = deps.root();
+		  if (root === void 0) throw new ScratchRootError();
+		  const roots = [root];
+		  const reusable = reusableScratch(deps.workspaces(), deps.sessions(), roots);
+		  if (reusable !== void 0) {
+		    await deps.openWorkspace(reusable.workspaceId);
+		    return;
+		  }
+		  const name = uniqueName(
+		    scratchName(deps.now()),
+		    (candidate) => nameTaken(candidate, deps.workspaces(), deps.sessions(), roots)
+		  );
+		  const sessionId = await deps.createSession(joinPath(root, name));
+		  const workspaceId = await deps.waitForWorkspace(sessionId, REGISTER_TIMEOUT_MS);
+		  if (workspaceId === void 0) deps.openSession(sessionId);
+		  else await deps.openWorkspace(workspaceId);
+		}
+		function createScratchStarter(deps, options) {
+		  let status = { busy: false, error: void 0 };
+		  let running;
+		  let clearTimer;
+		  const listeners = /* @__PURE__ */ new Set();
+		  const publish = (next) => {
+		    status = next;
+		    for (const listener of [...listeners]) listener();
+		  };
+		  const message = (error) => error instanceof ScratchRootError ? options.t("error.root") : options.t("error.create", {
+		    detail: error instanceof Error ? error.message : String(error)
+		  });
+		  return {
+		    start() {
+		      if (running !== void 0) return running;
+		      if (clearTimer !== void 0) clearTimeout(clearTimer);
+		      publish({ busy: true, error: void 0 });
+		      running = startScratch(deps).then(
+		        () => {
+		          running = void 0;
+		          publish({ busy: false, error: void 0 });
+		        },
+		        (error) => {
+		          running = void 0;
+		          options.warn("scratchpad: could not start a scratch", error);
+		          publish({ busy: false, error: message(error) });
+		          clearTimer = setTimeout(() => publish({ busy: false, error: void 0 }), ERROR_HOLD_MS);
+		        }
+		      );
+		      return running;
+		    },
+		    status: {
+		      getSnapshot: () => status,
+		      subscribe(listener) {
+		        listeners.add(listener);
+		        return () => {
+		          listeners.delete(listener);
+		        };
+		      }
+		    },
+		    dispose() {
+		      if (clearTimer !== void 0) clearTimeout(clearTimer);
+		      listeners.clear();
+		    }
+		  };
+		}
+		function waitForWorkspace(list, sessionId, timeoutMs) {
+		  const find = () => list.getSnapshot().items.find((workspace) => workspace.sessionIds.includes(sessionId))?.workspaceId;
+		  const found = find();
+		  if (found !== void 0) return Promise.resolve(found);
+		  return new Promise((resolve) => {
+		    let done = false;
+		    let unsubscribe;
+		    const finish = (value) => {
+		      if (done) return;
+		      done = true;
+		      clearTimeout(timer);
+		      unsubscribe?.();
+		      resolve(value);
+		    };
+		    const timer = setTimeout(() => finish(void 0), timeoutMs);
+		    unsubscribe = list.subscribe(() => {
+		      const workspaceId = find();
+		      if (workspaceId !== void 0) finish(workspaceId);
+		    });
+		    if (done) unsubscribe();
+		  });
+		}
+
+		// src/client/styles.ts
+		var SCRATCH_CSS = `
+		.dsh-scratch-footer {
+		  box-sizing: border-box;
+		  width: calc(100% + 4px);
+		  height: 42px;
+		  margin: 8px -2px 0;
+		  padding: 0 10px 0 8px;
+		  border: none;
+		  border-radius: 12px;
+		  background: transparent;
+		  color: var(--dsw-alias-label-primary);
+		  font-family: inherit;
+		  font-size: 14px;
+		  display: inline-flex;
+		  align-items: center;
+		  gap: 8px;
+		  cursor: pointer;
+		  overflow: hidden;
+		}
+		.dsh-scratch-footer:hover:not(:disabled) {
+		  background: var(--dsw-alias-interactive-bg-hover);
+		}
+		.dsh-scratch-footer:disabled {
+		  cursor: progress;
+		  opacity: 0.6;
+		}
+		.dsh-scratch-footer[data-rail] {
+		  width: 36px;
+		  height: 36px;
+		  margin: 0;
+		  padding: 0;
+		  gap: 0;
+		  justify-content: center;
+		  border-radius: 50%;
+		}
+		.dsh-scratch-footer svg {
+		  flex: none;
+		}
+		.dsh-scratch-label {
+		  min-width: 0;
+		  white-space: nowrap;
+		  overflow: hidden;
+		  text-overflow: ellipsis;
+		}
+		.dsh-scratch-label[data-error] {
+		  color: var(--dsw-alias-state-error-primary);
+		}
+		.dsh-scratch-chip {
+		  box-sizing: border-box;
+		  height: 28px;
+		  padding: 0 10px;
+		  border: 0.5px solid var(--dsw-alias-border-l3);
+		  border-radius: 999px;
+		  background: transparent;
+		  color: var(--dsw-alias-label-secondary);
+		  font-family: inherit;
+		  font-size: 13px;
+		  display: inline-flex;
+		  align-items: center;
+		  gap: 6px;
+		  white-space: nowrap;
+		  cursor: pointer;
+		}
+		.dsh-scratch-chip:hover:not(:disabled) {
+		  background: var(--dsw-alias-interactive-bg-hover);
+		  color: var(--dsw-alias-label-primary);
+		}
+		.dsh-scratch-chip:disabled {
+		  cursor: progress;
+		  opacity: 0.6;
+		}
+		`;
+
+		// src/client/index.tsx
+		var inject = [
+		  "slots",
+		  "locale",
+		  "configForms",
+		  "sessions",
+		  "workspaces",
+		  "uiWorkspace",
+		  "remote"
+		];
+		var PLUGIN_ID = "@1outres/dsh-plugin-scratchpad";
+		var NAMESPACE = "scratchpad";
+		var FOOTER_SLOT = "sidebar.footer.action";
+		var HERO_SLOT = "conversation.hero.options";
+		var COMMAND = "scratch";
+		function apply(ctx) {
+		  ctx.effect(() => ctx.locale.register(NAMESPACE, { en }), "scratchpad: dictionaries");
+		  ctx.effect(() => {
+		    const tag = document.createElement("style");
+		    tag.dataset.plugin = PLUGIN_ID;
+		    tag.dataset.pluginCss = `${PLUGIN_ID}/scratch.css`;
+		    tag.textContent = SCRATCH_CSS;
+		    document.head.append(tag);
+		    return () => {
+		      tag.remove();
+		    };
+		  }, "scratchpad: stylesheet");
+		  const t = ctx.locale.bind(NAMESPACE);
+		  const settings = ctx.configForms.get(NAMESPACE);
+		  ctx.effect(() => settings.subscribe(() => {
+		  }), "scratchpad: settings");
+		  const root = () => resolveRoot(settings.getSnapshot().value?.root, ctx.remote.$host.home);
+		  const starter = createScratchStarter(
+		    {
+		      root,
+		      workspaces: () => ctx.workspaces.list.getSnapshot(),
+		      sessions: () => ctx.sessions.list.getSnapshot(),
+		      createSession: (cwd) => ctx.sessions.create({ cwd }),
+		      openWorkspace: (workspaceId) => ctx.uiWorkspace.openWorkspace(workspaceId),
+		      openSession: (sessionId) => ctx.uiWorkspace.openSession(sessionId),
+		      waitForWorkspace: (sessionId, timeoutMs) => waitForWorkspace(ctx.workspaces.list, sessionId, timeoutMs),
+		      now: () => /* @__PURE__ */ new Date()
+		    },
+		    { t, warn: (message, error) => console.warn(message, error) }
+		  );
+		  ctx.effect(() => () => starter.dispose(), "scratchpad: starter");
+		  const face = { start: () => starter.start(), status: starter.status };
+		  ctx.effect(
+		    () => ctx.slots.inject(
+		      FOOTER_SLOT,
+		      () => ctx.slots.register(
+		        { name: FOOTER_SLOT, id: "scratchpad", locale: NAMESPACE, inject: () => face },
+		        NewScratchFooterButton
+		      )
+		    ),
+		    "scratchpad: sidebar button"
+		  );
+		  ctx.effect(
+		    () => ctx.slots.inject(
+		      HERO_SLOT,
+		      () => ctx.slots.register(
+		        {
+		          name: HERO_SLOT,
+		          id: "scratchpad",
+		          locale: NAMESPACE,
+		          inject: (sessionId) => ({
+		            ...face,
+		            sessionId,
+		            sessions: ctx.sessions.list,
+		            isRoot: (cwd) => {
+		              const resolved = root();
+		              return resolved !== void 0 && isRootPath(cwd, [resolved]);
+		            }
+		          })
+		        },
+		        NewScratchChip
+		      )
+		    ),
+		    "scratchpad: new session chip"
+		  );
+		  ctx.inject(["commandUi"], (child) => {
+		    const commandUi = child.commandUi;
+		    if (commandUi === void 0) return;
+		    child.effect(
+		      () => commandUi.register({
+		        name: COMMAND,
+		        label: () => t("command.label"),
+		        description: () => t("command.description"),
+		        icon: IconScratch,
+		        available: () => true,
+		        ui: {
+		          kind: "action",
+		          run: () => {
+		            void starter.start();
+		          }
+		        }
+		      }),
+		      "scratchpad: /scratch command"
+		    );
+		  });
+		}
+
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,469 @@
+// src/index.ts
+import { homedir } from "node:os";
+import z from "@deepseek-ai/schemastery";
+
+// src/host/fs.ts
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmdirSync,
+  statSync
+} from "node:fs";
+var nodeFs = {
+  exists: (path) => existsSync(path),
+  isEmptyDir: (path) => {
+    try {
+      return statSync(path).isDirectory() && readdirSync(path).length === 0;
+    } catch {
+      return false;
+    }
+  },
+  rename: (from, to) => renameSync(from, to),
+  removeEmptyDir: (path) => rmdirSync(path),
+  ensureDir: (path) => {
+    mkdirSync(path, { recursive: true });
+  },
+  realpath: (path) => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return void 0;
+    }
+  },
+  listDirs: (path) => {
+    try {
+      return readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    } catch {
+      return [];
+    }
+  }
+};
+
+// src/shared/paths.ts
+var DEFAULT_ROOT = "~/.dsh/scratchpad";
+var ARCHIVE_DIR = ".archived";
+function trimTrailingSlashes(path) {
+  let end = path.length;
+  while (end > 1 && (path[end - 1] === "/" || path[end - 1] === "\\")) end--;
+  return path.slice(0, end);
+}
+function expandHome(path, home) {
+  const value = path.trim();
+  if (value === "~" || value.startsWith("~/") || value.startsWith("~\\")) {
+    if (home === void 0 || home === "") return void 0;
+    return trimTrailingSlashes(`${trimTrailingSlashes(home)}${value.slice(1)}`);
+  }
+  return trimTrailingSlashes(value);
+}
+function isAbsolutePath(path) {
+  return path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+function resolveRoot(configured, home) {
+  const raw = configured === void 0 || configured.trim() === "" ? DEFAULT_ROOT : configured;
+  const expanded = expandHome(raw, home);
+  if (expanded === void 0 || !isAbsolutePath(expanded)) return void 0;
+  return expanded;
+}
+function separatorOf(root) {
+  return /^[A-Za-z]:\\/.test(root) || root.startsWith("\\\\") ? "\\" : "/";
+}
+function joinPath(dir, name2) {
+  const base = trimTrailingSlashes(dir);
+  const sep = separatorOf(base);
+  return base.endsWith(sep) ? `${base}${name2}` : `${base}${sep}${name2}`;
+}
+function splitPath(path) {
+  const trimmed = trimTrailingSlashes(path);
+  const at = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+  if (at < 0) return { parent: "", name: trimmed };
+  return {
+    parent: at === 0 ? trimmed.slice(0, 1) : trimmed.slice(0, at),
+    name: trimmed.slice(at + 1)
+  };
+}
+function isScratchName(name2) {
+  return name2 !== "" && !name2.startsWith(".") && !/[\\/]/.test(name2);
+}
+function scratchNameOf(path, roots) {
+  if (path === void 0) return void 0;
+  const { parent, name: name2 } = splitPath(path);
+  if (!isScratchName(name2)) return void 0;
+  return roots.some((root) => trimTrailingSlashes(root) === parent) ? name2 : void 0;
+}
+
+// src/host/scratchpad.ts
+var SETTLE_TIMEOUT_MS = 12e4;
+var POLL_MS = 2e3;
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var Scratchpad = class {
+  options;
+  headers = /* @__PURE__ */ new Map();
+  /** Session id to scratch name, for top-level Sessions created in a scratch. */
+  nameOf = /* @__PURE__ */ new Map();
+  archived = /* @__PURE__ */ new Set();
+  chains = /* @__PURE__ */ new Map();
+  abort = new AbortController();
+  early = [];
+  canonicalRoot;
+  ready = false;
+  constructor(options) {
+    this.options = options;
+  }
+  /** Canonical root once it exists, otherwise the configured spelling. */
+  rootPath() {
+    if (this.canonicalRoot === void 0) {
+      this.canonicalRoot = this.options.fs.realpath(this.options.root);
+    }
+    return this.canonicalRoot ?? this.options.root;
+  }
+  /** Every spelling a Session cwd may use for the root. */
+  roots() {
+    const canonical = this.rootPath();
+    return canonical === this.options.root ? [canonical] : [this.options.root, canonical];
+  }
+  /** Directory of a scratch while it is in use. */
+  pathOf(name2) {
+    return joinPath(this.rootPath(), name2);
+  }
+  /** Directory of a scratch while it is archived. */
+  archivePathOf(name2) {
+    return joinPath(joinPath(this.rootPath(), ARCHIVE_DIR), name2);
+  }
+  /** Index the existing Sessions, then catch up with changes made while the plugin was off. */
+  async start() {
+    this.archived = new Set(this.options.registry.archivedSessionIds);
+    await this.loadHeaders();
+    this.ready = true;
+    for (const [sessionId, source] of this.early.splice(0)) this.onSessionStarted(sessionId, source);
+    const names = new Set(this.nameOf.values());
+    await Promise.all([...names].map((name2) => this.enqueue(name2, () => this.reconcile(name2))));
+  }
+  /** Stop waiting moves. Directories are never left half-moved: each move is one rename. */
+  dispose() {
+    this.abort.abort();
+  }
+  /** Resolve once no operation is queued. */
+  async idle() {
+    while (this.chains.size > 0) await Promise.all([...this.chains.values()]);
+  }
+  /**
+   * An Agent started for a Session (`agent/created`). Registers a new scratch,
+   * or moves an archived scratch back when a Session that is not archived needs
+   * it, such as a fork made from an archived row.
+   */
+  onSessionStarted(sessionId, source) {
+    const header = this.options.liveHeader(sessionId);
+    if (header === void 0) return;
+    this.remember(header);
+    if (!this.ready) {
+      this.early.push([sessionId, source]);
+      return;
+    }
+    const name2 = this.nameOf.get(sessionId);
+    if (name2 === void 0 || this.archived.has(sessionId)) return;
+    const { fs } = this.options;
+    const path = this.pathOf(name2);
+    const shared = this.members(name2).some((member) => member.id !== sessionId);
+    if (shared && fs.exists(this.archivePathOf(name2)) && (!fs.exists(path) || fs.isEmptyDir(path))) {
+      if (this.restoreDirectory(name2)) void this.enqueue(name2, () => this.register(name2));
+      return;
+    }
+    if (source === "startup" && !shared && fs.exists(path) && this.workspaceFor(name2) === void 0) {
+      void this.enqueue(name2, () => this.registerNew(name2, sessionId));
+    }
+  }
+  /**
+   * The registry's archive set changed (`domain/changed`). Unarchived scratches
+   * move back before this returns; archived ones move once their work stops.
+   */
+  onArchiveSetChanged(next) {
+    const previous = this.archived;
+    this.archived = new Set(next);
+    if (!this.ready) return;
+    for (const id of previous) {
+      if (this.archived.has(id)) continue;
+      const name2 = this.nameOf.get(id);
+      if (name2 === void 0 || !this.options.fs.exists(this.archivePathOf(name2))) continue;
+      if (this.restoreDirectory(name2)) void this.enqueue(name2, () => this.register(name2));
+    }
+    const archivedNames = /* @__PURE__ */ new Set();
+    for (const id of this.archived) {
+      if (previous.has(id)) continue;
+      const name2 = this.nameOf.get(id);
+      if (name2 !== void 0) archivedNames.add(name2);
+    }
+    for (const name2 of archivedNames) void this.enqueue(name2, () => this.archiveWhenSettled(name2));
+  }
+  remember(header) {
+    this.headers.set(header.id, header);
+    if (header.origin === "subagent") return;
+    const name2 = scratchNameOf(header.cwd, this.roots());
+    if (name2 !== void 0) this.nameOf.set(header.id, name2);
+  }
+  async loadHeaders() {
+    for (const header of await this.options.headers()) this.remember(header);
+  }
+  /** Top-level Sessions created in a scratch, oldest first. */
+  members(name2) {
+    const members = [];
+    for (const [id, scratch] of this.nameOf) {
+      const header = this.headers.get(id);
+      if (scratch === name2 && header !== void 0) members.push(header);
+    }
+    return members.sort((left, right) => left.createdAt - right.createdAt);
+  }
+  workspaceFor(name2) {
+    const path = this.pathOf(name2);
+    return this.options.registry.list().find((workspace) => workspace.path === path);
+  }
+  allArchived(workspace) {
+    const ids = workspace.sessionIds;
+    return ids.length > 0 && ids.every((id) => this.archived.has(id));
+  }
+  enqueue(name2, operation) {
+    const previous = this.chains.get(name2) ?? Promise.resolve();
+    const next = previous.then(() => this.abort.signal.aborted ? void 0 : operation()).catch((error) => {
+      this.options.logger.warn(`scratchpad: ${name2}: ${describe(error)}`);
+    });
+    this.chains.set(name2, next);
+    void next.then(() => {
+      if (this.chains.get(name2) === next) this.chains.delete(name2);
+    });
+    return next;
+  }
+  /** Move an archived scratch back to the root. Synchronous. */
+  restoreDirectory(name2) {
+    const { fs, logger } = this.options;
+    const from = this.archivePathOf(name2);
+    const to = this.pathOf(name2);
+    try {
+      if (fs.exists(to)) {
+        if (!fs.isEmptyDir(to)) {
+          logger.warn(`scratchpad: ${name2} stays archived: ${to} already exists and is not empty`);
+          return false;
+        }
+        fs.removeEmptyDir(to);
+      }
+      fs.rename(from, to);
+    } catch (error) {
+      logger.warn(`scratchpad: could not restore ${name2}: ${describe(error)}`);
+      return false;
+    }
+    logger.info(`scratchpad: restored ${name2} from the archive`);
+    return true;
+  }
+  /** Register a restored scratch and give it back its Sessions, newest first. */
+  async register(name2) {
+    const path = this.pathOf(name2);
+    if (!this.options.fs.exists(path)) return;
+    await this.loadHeaders();
+    const workspace = this.workspaceFor(name2) ?? await this.options.registry.create(path, name2);
+    for (const member of this.members(name2)) {
+      if (workspace.sessionIds.includes(member.id)) continue;
+      try {
+        await workspace.attachSession(member.id);
+      } catch (error) {
+        this.options.logger.warn(
+          `scratchpad: could not attach ${member.id} to ${name2}: ${describe(error)}`
+        );
+      }
+    }
+  }
+  /** Register a scratch that a new Session was just created in. */
+  async registerNew(name2, sessionId) {
+    const { registry, registerRoot } = this.options;
+    const root = this.rootPath();
+    if (registerRoot && !registry.list().some((workspace2) => workspace2.path === root)) {
+      await registry.create(root);
+    }
+    const workspace = this.workspaceFor(name2) ?? await registry.create(this.pathOf(name2), name2);
+    if (!workspace.sessionIds.includes(sessionId)) await workspace.attachSession(sessionId);
+  }
+  /** Move a registered scratch to the archive once all its Sessions are archived and idle. */
+  async archiveWhenSettled(name2) {
+    const { fs, logger, registry } = this.options;
+    const workspace = this.workspaceFor(name2);
+    if (workspace === void 0 || !this.allArchived(workspace)) return;
+    const path = this.pathOf(name2);
+    const target = this.archivePathOf(name2);
+    if (!fs.exists(path)) {
+      if (fs.exists(target)) await registry.delete(workspace.id);
+      return;
+    }
+    if (!await this.settle(name2, workspace)) return;
+    const current = this.workspaceFor(name2);
+    if (current === void 0 || !this.allArchived(current)) return;
+    if (fs.exists(target)) {
+      logger.warn(`scratchpad: ${name2} stays in place: ${target} already exists`);
+      return;
+    }
+    try {
+      fs.ensureDir(joinPath(this.rootPath(), ARCHIVE_DIR));
+      fs.rename(path, target);
+    } catch (error) {
+      logger.warn(`scratchpad: could not archive ${name2}: ${describe(error)}`);
+      return;
+    }
+    logger.info(`scratchpad: archived ${name2} to ${target}`);
+    await registry.delete(current.id);
+  }
+  /** Wait until no Session of the scratch runs anything. */
+  async settle(name2, workspace) {
+    const { now, sleep: sleep2, busy, logger } = this.options;
+    const deadline = now() + (this.options.settleTimeoutMs ?? SETTLE_TIMEOUT_MS);
+    const poll = this.options.pollMs ?? POLL_MS;
+    for (; ; ) {
+      if (this.abort.signal.aborted || !this.allArchived(workspace)) return false;
+      let running = false;
+      for (const id of workspace.sessionIds) {
+        try {
+          running = await busy(id);
+        } catch {
+          running = true;
+        }
+        if (running) break;
+      }
+      if (!running) return true;
+      if (now() >= deadline) {
+        logger.warn(`scratchpad: ${name2} stays in place: its sessions are still running`);
+        return false;
+      }
+      try {
+        await sleep2(poll, this.abort.signal);
+      } catch {
+        return false;
+      }
+    }
+  }
+  /** Catch up one scratch at startup. */
+  async reconcile(name2) {
+    const members = this.members(name2);
+    if (members.length === 0) return;
+    if (members.every((member) => this.archived.has(member.id))) {
+      await this.archiveWhenSettled(name2);
+      return;
+    }
+    const { fs } = this.options;
+    const path = this.pathOf(name2);
+    if (fs.exists(this.archivePathOf(name2)) && (!fs.exists(path) || fs.isEmptyDir(path))) {
+      if (this.restoreDirectory(name2)) await this.register(name2);
+    }
+  }
+};
+
+// src/index.ts
+var name = "scratchpad";
+var inject = ["workspaceRegistry", "sessionPersistence", "sessions"];
+var Config = z.object({
+  root: z.string().default(DEFAULT_ROOT).description("Directory that holds the scratches. A leading ~ is your home directory."),
+  registerRoot: z.boolean().default(true).description(
+    "Register the root as a workspace when a scratch is created, so Workspace Tree grouping nests every scratch under it."
+  )
+});
+function archivedIdsOf(change) {
+  if (change.domain !== "workspace" || change.table !== "" || change.operation !== "put") {
+    return void 0;
+  }
+  const value = change.value;
+  if (typeof value !== "object" || value === null || !Array.isArray(value.workspaceIds)) {
+    return void 0;
+  }
+  const ids = value.archivedSessionIds ?? [];
+  if (!Array.isArray(ids) || !ids.every((id) => typeof id === "string")) return void 0;
+  return ids;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", stop);
+      resolve();
+    }, ms);
+    const stop = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", stop, { once: true });
+  });
+}
+function apply(ctx, config) {
+  const services = ctx;
+  const events = ctx;
+  const logger = {
+    info: (message) => ctx.logger.info(message),
+    warn: (message) => ctx.logger.warn(message)
+  };
+  const root = resolveRoot(config.root, homedir());
+  if (root === void 0) {
+    logger.warn(`scratchpad: root '${config.root}' is not an absolute path; nothing is managed`);
+    return;
+  }
+  const pad = new Scratchpad({
+    root,
+    registerRoot: config.registerRoot,
+    registry: services.workspaceRegistry,
+    headers: async () => {
+      const byId = /* @__PURE__ */ new Map();
+      for (const session of await services.sessionPersistence.list()) {
+        byId.set(session.header.id, session.header);
+      }
+      for (const session of services.sessions.list()) byId.set(session.header.id, session.header);
+      return [...byId.values()];
+    },
+    liveHeader: (sessionId) => services.sessions.get(sessionId)?.header,
+    busy: async (sessionId) => {
+      const activity = await events.waterfall(
+        "workspace/session-activity",
+        { sessionId },
+        () => Promise.resolve([])
+      );
+      if (activity.length > 0) return true;
+      const agent = ctx.get("agents")?.get(sessionId);
+      const terminals = ctx.get("terminals");
+      return agent !== void 0 && terminals?.hasOwnerActivity(agent) === true;
+    },
+    fs: nodeFs,
+    logger,
+    sleep,
+    now: Date.now
+  });
+  events.on("agent/created", (payload) => {
+    try {
+      pad.onSessionStarted(payload.agent.id, payload.source);
+    } catch (error) {
+      logger.warn(`scratchpad: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+  events.on("domain/changed", (change) => {
+    const archived = archivedIdsOf(change);
+    if (archived === void 0) return;
+    try {
+      pad.onArchiveSetChanged(archived);
+    } catch (error) {
+      logger.warn(`scratchpad: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+  ctx.effect(() => {
+    pad.start().catch((error) => {
+      logger.warn(
+        `scratchpad: startup check failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+    return () => pad.dispose();
+  }, "scratchpad: archive bookkeeping");
+}
+export {
+  Config,
+  apply,
+  archivedIdsOf,
+  inject,
+  name
+};

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Scratchpad",
+    "description": "One click opens a session in a new empty directory, registered as its own workspace, for one-off scripts, experiments, research and writing. Archiving every session in a scratch moves its directory to .archived; unarchiving moves it back."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "スクラッチパッド",
+    "description": "ワンクリックで新しい空のディレクトリを作り、専用のワークスペースとして Session を開きます。使い捨てのスクリプトや小さな実験、調査、執筆に。スクラッチの Session をすべてアーカイブするとディレクトリを .archived へ移し、アーカイブを解除すると元に戻します。"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "草稿区",
+    "description": "一键在新建的空目录中打开会话，该目录注册为独立的工作区，适合一次性脚本、小实验、调研和写作。草稿中的会话全部归档后，其目录会移入 .archived；取消归档时移回原处。"
+  }
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@1outres/dsh-plugin-scratchpad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "One-click scratch sessions for DeepSeek Harness: each gets a new empty directory registered as its own workspace, moved aside when archived.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1outres/my-dsh-plugins.git",
+    "directory": "packages/dsh-plugin-scratchpad"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "scratchpad",
+    "deepseek-harness"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.5 <0.3.0",
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "react": "^18.2.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": [
+        "./cordis.patch.yml"
+      ]
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-commands",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  },
+  "scripts": {}
 }