@zerwiz/ymir 0.1.33 → 0.1.35

package/apps/sessrumnir/src/main/session-paths.test.ts

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+  sanitizePath,
+  sessionDirName,
+  desanitizeSessionDir,
+  isSessionArtifactDir,
+  projectNameFromPath,
+  pathsEqual,
+} from './session-paths'
+
+/**
+ * OMP writes each subagent's transcript into `<timestamp>_<uuid>/` beside the
+ * session store root. Observed live: the index read that as a project, listed
+ * `SecurityReview.jsonl` as a chat, and spawned a real agent against it.
+ */
+test('a session artifact directory is not mistaken for a project', () => {
+  assert.equal(isSessionArtifactDir('2026-08-24T18-15-06-360Z_01a034fb-b578-7276-a10c-feee5492c0eb'), true)
+})
+
+test('real project directories are still listed', () => {
+  // Pi's sanitized form, and the two odd names OMP creates in practice.
+  assert.equal(isSessionArtifactDir('--home-alice--'), false)
+  assert.equal(isSessionArtifactDir('--mnt-data-Projects-thing--'), false)
+  assert.equal(isSessionArtifactDir('-tmp'), false)
+  assert.equal(isSessionArtifactDir('-'), false)
+  assert.equal(isSessionArtifactDir('C--Users-alice--'), false)
+})
+
+test('the guard needs both a timestamp and a uuid, not either alone', () => {
+  assert.equal(isSessionArtifactDir('2026-08-24T18-15-06-360Z'), false)
+  assert.equal(isSessionArtifactDir('01a034fb-b578-7276-a10c-feee5492c0eb'), false)
+  assert.equal(isSessionArtifactDir('2026-08-24T18-15-06-360Z_not-a-uuid'), false)
+})
+
+test('sanitizePath encodes POSIX paths like Pi', () => {
+  assert.equal(sanitizePath('/home/alice'), '--home-alice--')
+  assert.equal(sanitizePath('/home/alice/Projects/app'), '--home-alice-Projects-app--')
+})
+
+test('sanitizePath encodes Windows paths (drive colon + backslashes)', () => {
+  assert.equal(sanitizePath('C:\\Users\\UPN'), '--C--Users-UPN--')
+  assert.equal(
+    sanitizePath('C:\\Users\\UPN\\documents\\workday'),
+    '--C--Users-UPN-documents-workday--'
+  )
+})
+
+test('sanitizePath(workspace) matches the on-disk Windows session dir', () => {
+  // Regression: workspace match used to fail on Windows, leaking the raw slug.
+  const wsPath = 'C:\\Users\\UPN\\documents\\workday'
+  const onDiskDir = '--C--Users-UPN-documents-workday--'
+  assert.equal(sanitizePath(wsPath), onDiskDir)
+})
+
+test('sessionDirName strips the root and a leading backslash', () => {
+  const root = 'C:\\Users\\UPN\\.pi\\agent\\sessions'
+  const dir = 'C:\\Users\\UPN\\.pi\\agent\\sessions\\--C--Users-UPN-documents-workday--'
+  assert.equal(sessionDirName(dir, root), '--C--Users-UPN-documents-workday--')
+})
+
+test('sessionDirName strips the root and a leading forward slash', () => {
+  const root = '/home/alice/.pi/agent/sessions'
+  const dir = '/home/alice/.pi/agent/sessions/--home-alice--'
+  assert.equal(sessionDirName(dir, root), '--home-alice--')
+})
+
+test('desanitizeSessionDir reverses POSIX names', () => {
+  assert.equal(desanitizeSessionDir('--home-alice--'), '/home/alice')
+})
+
+test('desanitizeSessionDir rebuilds a native Windows path (drive signature)', () => {
+  // Regression: must produce "C:\..." — not "/C/..." — so the decoded path
+  // stays valid when reused as a workspace path.
+  assert.equal(desanitizeSessionDir('--C--Users-UPN--'), 'C:\\Users\\UPN')
+  assert.equal(
+    desanitizeSessionDir('--C--Users-UPN-documents-workday--'),
+    'C:\\Users\\UPN\\documents\\workday'
+  )
+})
+
+test('desanitizeSessionDir handles a bare Windows drive root', () => {
+  assert.equal(desanitizeSessionDir('--C----'), 'C:\\')
+})
+
+test('desanitizeSessionDir passes through non-sanitized input', () => {
+  assert.equal(desanitizeSessionDir('not-a-session-dir'), 'not-a-session-dir')
+})
+
+test('projectNameFromPath returns the basename regardless of separator', () => {
+  assert.equal(projectNameFromPath('C:\\Users\\UPN\\documents\\workday'), 'workday')
+  assert.equal(projectNameFromPath('/home/alice/app'), 'app')
+  assert.equal(projectNameFromPath('/C/Users/UPN/documents/workday'), 'workday')
+})
+
+test('pathsEqual ignores case when case-insensitive (Windows)', () => {
+  assert.equal(
+    pathsEqual('C:\\Users\\UPN\\Documents\\workday', 'C:\\Users\\UPN\\documents\\workday', true),
+    true
+  )
+  // Also works for encoded session-dir names.
+  assert.equal(pathsEqual('--C--Users-UPN-Documents-workday--', '--C--Users-UPN-documents-workday--', true), true)
+  assert.equal(pathsEqual('C:\\a', 'C:\\b', true), false)
+})
+
+test('pathsEqual is exact when case-sensitive (Linux/macOS)', () => {
+  // Regression guard: must NOT change behavior on case-sensitive systems.
+  assert.equal(pathsEqual('/home/alice/App', '/home/alice/app', false), false)
+  assert.equal(pathsEqual('/home/alice/app', '/home/alice/app', false), true)
+})

package/apps/sessrumnir/src/main/session-paths.ts

@@ -0,0 +1,88 @@
+/**
+ * Helpers for mapping between real project paths and the directory names Pi
+ * uses under `~/.pi/agent/sessions`.
+ *
+ * Pi encodes a project path into a session directory name by replacing path
+ * separators — and, on Windows, the drive-letter colon — with `-`, then
+ * wrapping the result in `--`:
+ *
+ *   POSIX    /home/alice                    -> --home-alice--
+ *   Windows  C:\Users\UPN\documents\workday -> --C--Users-UPN-documents-workday--
+ *
+ * Decoding is inherently lossy (real `-` characters are indistinguishable from
+ * separators), so callers should prefer matching against known workspace paths
+ * and fall back to `desanitizeSessionDir` only for display.
+ */
+
+/** Extension of a Pi session file. */
+export const JSONL_EXTENSION = '.jsonl'
+
+/** Encode a real filesystem path the same way Pi names its session directory. */
+export function sanitizePath(p: string): string {
+  // Drop a single leading separator so POSIX "/home/x" -> "--home-x--".
+  // Windows paths start with a drive letter, so nothing is stripped there.
+  const body = p.replace(/^[\\/]/, '').replace(/[\\/:]/g, '-')
+  return `--${body}--`
+}
+
+/**
+ * The Pi session directory name for `dir`, relative to `sessionsRoot`.
+ * Strips the root prefix and any leading separator of either kind, and
+ * normalizes backslashes so the result compares equal across platforms.
+ */
+export function sessionDirName(dir: string, sessionsRoot: string): string {
+  const rel = dir.startsWith(sessionsRoot) ? dir.slice(sessionsRoot.length) : dir
+  return rel.replace(/^[\\/]+/, '').replace(/\\/g, '/')
+}
+
+/**
+ * A session's own artifact directory, named after the session file rather than
+ * after a project path: `<ISO timestamp>_<uuid>`.
+ *
+ * OMP writes each subagent's transcript into one of these beside the session
+ * store root. They are not projects, and their contents are not user sessions.
+ * Left unguarded, the index listed `SecurityReview.jsonl` as a chat, and
+ * opening it spawned a real agent against a subagent's transcript.
+ */
+const SESSION_ARTIFACT_DIR_RE = /^\d{4}-\d{2}-\d{2}T[\d-]+Z_[0-9a-fA-F-]{36}$/
+
+export function isSessionArtifactDir(dirName: string): boolean {
+  return SESSION_ARTIFACT_DIR_RE.test(dirName)
+}
+
+/**
+ * Best-effort (lossy) reversal of `sanitizePath`.
+ * Returns the directory name unchanged if it isn't a Pi-sanitized name.
+ *
+ * Reconstructs a Windows path when the name carries the drive-letter
+ * signature ("C:\" encodes to "C--", i.e. a single-letter segment followed by
+ * an empty one), otherwise a POSIX path. Keeping decoded paths native means
+ * they display correctly and stay valid when reused (e.g. as a workspace path).
+ */
+export function desanitizeSessionDir(dirName: string): string {
+  if (!dirName.startsWith('--') || !dirName.endsWith('--')) {
+    return dirName
+  }
+  const inner = dirName.slice(2, -2)
+  const rawSegments = inner.split('-')
+
+  // Windows: a leading "<letter>--" came from "<letter>:\".
+  if (rawSegments.length >= 2 && /^[A-Za-z]$/.test(rawSegments[0]) && rawSegments[1] === '') {
+    const drive = rawSegments[0].toUpperCase()
+    const rest = rawSegments.slice(2).filter(Boolean)
+    return rest.length ? `${drive}:\\${rest.join('\\')}` : `${drive}:\\`
+  }
+
+  // POSIX: drop empty segments and rejoin with '/'.
+  const segments = rawSegments.filter(Boolean)
+  return '/' + segments.join('/')
+}
+
+/** Separator-agnostic basename; handles both `/` and `\` and trailing separators. */
+export function projectNameFromPath(p: string): string {
+  const parts = p.split(/[\\/]/).filter(Boolean)
+  return parts.length ? parts[parts.length - 1] : p
+}
+
+// Single implementation lives in shared so main + renderer cannot drift.
+export { pathsEqual, pathGroupKey } from '../shared/path-compare'

package/apps/sessrumnir/src/main/session-tags.test.ts

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { mkdtemp } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { configureGuiDataDir } from './app-data-paths'
+import { SessionTagManager } from './session-tags'
+
+async function freshManager(): Promise<SessionTagManager> {
+  const dir = await mkdtemp(join(tmpdir(), 'pi-tags-'))
+  configureGuiDataDir(dir)
+  return new SessionTagManager()
+}
+
+test('setTags normalizes case, #, whitespace and dedupes', async () => {
+  const mgr = await freshManager()
+  await mgr.setTags('s1', ['  #Bug ', 'bug', 'FEATURE'])
+  assert.deepEqual(await mgr.getTags('s1'), ['bug', 'feature'])
+})
+
+test('setTags with empty list clears the session', async () => {
+  const mgr = await freshManager()
+  await mgr.setTags('s1', ['x'])
+  await mgr.setTags('s1', ['   ', '#'])
+  assert.deepEqual(await mgr.getTags('s1'), [])
+})
+
+test('addTag is idempotent and rejects over-long tags', async () => {
+  const mgr = await freshManager()
+  await mgr.addTag('s1', 'alpha')
+  await mgr.addTag('s1', 'alpha')
+  assert.deepEqual(await mgr.getTags('s1'), ['alpha'])
+  const tooLong = 'x'.repeat(40)
+  await mgr.addTag('s1', tooLong)
+  assert.deepEqual(await mgr.getTags('s1'), ['alpha'], 'over-length tag is ignored')
+})
+
+test('removeTag drops the tag and empties the session when last', async () => {
+  const mgr = await freshManager()
+  await mgr.setTags('s1', ['a', 'b'])
+  await mgr.removeTag('s1', '#A') // normalization applies on remove too
+  assert.deepEqual(await mgr.getTags('s1'), ['b'])
+  await mgr.removeTag('s1', 'b')
+  assert.deepEqual(await mgr.getAllTags(), {})
+})
+
+test('getSessionsWithTag and getAllUsedTags aggregate across sessions', async () => {
+  const mgr = await freshManager()
+  await mgr.setTags('s1', ['shared', 'one'])
+  await mgr.setTags('s2', ['shared', 'two'])
+  assert.deepEqual((await mgr.getSessionsWithTag('shared')).sort(), ['s1', 's2'])
+  assert.deepEqual(await mgr.getAllUsedTags(), ['one', 'shared', 'two'])
+})
+
+test('tags persist across manager instances', async () => {
+  const mgr = await freshManager()
+  await mgr.setTags('s1', ['keep'])
+  // Reuse the same configured dir with a new instance.
+  const reloaded = new SessionTagManager()
+  assert.deepEqual(await reloaded.getTags('s1'), ['keep'])
+})

package/apps/sessrumnir/src/main/session-tags.ts

@@ -0,0 +1,253 @@
+import { readFile, writeFile, mkdir } from 'fs/promises'
+import { join } from 'path'
+import { existsSync } from 'fs'
+import { deriveAutoTag } from './auto-tag'
+import { getGuiDataPath } from './app-data-paths'
+
+/**
+ * Session tags store.
+ * Maps session IDs to arrays of tags.
+ * Stored in the Electron userData directory.
+ */
+
+const TAGS_FILE_NAME = 'session-tags.json'
+const AUTO_TAGS_FILE_NAME = 'session-auto-tags.json'
+const MAX_TAG_LENGTH = 32
+
+interface TagsStore {
+  [sessionId: string]: string[]
+}
+
+/**
+ * On-disk shape for machine-derived tags. `tags` holds the currently assigned
+ * auto-tag per session; `processed` records every session we've already
+ * attempted, so a removed auto-tag is never re-derived on the next load.
+ */
+interface AutoTagsStore {
+  tags: Record<string, string>
+  processed: string[]
+}
+
+export class SessionTagManager {
+  private tagsPath: string
+  private cache: TagsStore = {}
+  private loaded = false
+
+  private autoTagsPath: string
+  private autoTags: Record<string, string> = {}
+  private autoProcessed = new Set<string>()
+  private autoLoaded = false
+
+  constructor() {
+    this.tagsPath = getGuiDataPath(TAGS_FILE_NAME)
+    this.autoTagsPath = getGuiDataPath(AUTO_TAGS_FILE_NAME)
+  }
+
+  async getTags(sessionId: string): Promise<string[]> {
+    await this.ensureLoaded()
+    return this.cache[sessionId] ?? []
+  }
+
+  async getAllTags(): Promise<TagsStore> {
+    await this.ensureLoaded()
+    return { ...this.cache }
+  }
+
+  async setTags(sessionId: string, tags: string[]): Promise<void> {
+    await this.ensureLoaded()
+    // Normalize: lowercase, trim, remove empties, dedupe
+    const normalized = [...new Set(
+      tags
+        .map((t) => t.trim().toLowerCase().replace(/^#/, ''))
+        .filter((t) => t.length > 0 && t.length <= MAX_TAG_LENGTH)
+    )]
+
+    if (normalized.length === 0) {
+      delete this.cache[sessionId]
+    } else {
+      this.cache[sessionId] = normalized
+      // Manual tags supersede the auto-tag; drop it but keep processed.
+      await this.clearAutoTag(sessionId, true)
+    }
+
+    await this.save()
+  }
+
+  async addTag(sessionId: string, tag: string): Promise<string[]> {
+    await this.ensureLoaded()
+    const existing = this.cache[sessionId] ?? []
+    const normalized = tag.trim().toLowerCase().replace(/^#/, '')
+    if (normalized.length === 0 || normalized.length > MAX_TAG_LENGTH) return existing
+    if (existing.includes(normalized)) return existing
+
+    this.cache[sessionId] = [...existing, normalized]
+    await this.save()
+    // A manual tag supersedes the auto-tag; drop it but keep the session marked
+    // processed so it isn't re-derived later.
+    await this.clearAutoTag(sessionId, true)
+    return this.cache[sessionId]
+  }
+
+  async removeTag(sessionId: string, tag: string): Promise<string[]> {
+    await this.ensureLoaded()
+    const existing = this.cache[sessionId] ?? []
+    const normalized = tag.trim().toLowerCase().replace(/^#/, '')
+    this.cache[sessionId] = existing.filter((t) => t !== normalized)
+
+    if (this.cache[sessionId].length === 0) {
+      delete this.cache[sessionId]
+    }
+
+    await this.save()
+    return this.cache[sessionId] ?? []
+  }
+
+  async getSessionsWithTag(tag: string): Promise<string[]> {
+    await this.ensureLoaded()
+    const normalized = tag.trim().toLowerCase().replace(/^#/, '')
+    const sessionIds: string[] = []
+
+    for (const [sessionId, tags] of Object.entries(this.cache)) {
+      if (tags.includes(normalized)) {
+        sessionIds.push(sessionId)
+      }
+    }
+
+    return sessionIds
+  }
+
+  async getAllUsedTags(): Promise<string[]> {
+    await this.ensureLoaded()
+    const allTags = new Set<string>()
+    for (const tags of Object.values(this.cache)) {
+      for (const tag of tags) {
+        allTags.add(tag)
+      }
+    }
+    return [...allTags].sort()
+  }
+
+  // ─── Auto-tags ──────────────────────────────────────────────────────────
+
+  async getAutoTags(): Promise<Record<string, string>> {
+    await this.ensureAutoLoaded()
+    return { ...this.autoTags }
+  }
+
+  /**
+   * For each supplied session, derive and persist an auto-tag when it has no
+   * manual tags and hasn't been processed before. Returns the full auto-tag map.
+   */
+  async ensureAutoTags(sessions: Array<{ sessionId: string; path: string }>): Promise<Record<string, string>> {
+    await this.ensureLoaded()
+    await this.ensureAutoLoaded()
+
+    let changed = false
+    for (const { sessionId, path } of sessions) {
+      if (this.autoProcessed.has(sessionId)) continue
+      if ((this.cache[sessionId]?.length ?? 0) > 0) continue
+
+      const derived = await deriveAutoTag(path)
+      this.autoProcessed.add(sessionId)
+      if (derived) {
+        const normalized = derived.trim().toLowerCase().replace(/^#/, '')
+        if (normalized.length > 0 && normalized.length <= MAX_TAG_LENGTH) {
+          this.autoTags[sessionId] = normalized
+        }
+      }
+      changed = true
+    }
+
+    if (changed) await this.saveAuto()
+    return { ...this.autoTags }
+  }
+
+  /** Remove an auto-tag at the user's request; stays processed so it won't return. */
+  async removeAutoTag(sessionId: string): Promise<void> {
+    await this.clearAutoTag(sessionId, true)
+  }
+
+  /** Forget a session entirely (used when the session is deleted). */
+  async forgetAuto(sessionId: string): Promise<void> {
+    await this.clearAutoTag(sessionId, false)
+  }
+
+  private async clearAutoTag(sessionId: string, keepProcessed: boolean): Promise<void> {
+    await this.ensureAutoLoaded()
+    let changed = false
+    if (sessionId in this.autoTags) {
+      delete this.autoTags[sessionId]
+      changed = true
+    }
+    if (keepProcessed) {
+      if (!this.autoProcessed.has(sessionId)) {
+        this.autoProcessed.add(sessionId)
+        changed = true
+      }
+    } else if (this.autoProcessed.delete(sessionId)) {
+      changed = true
+    }
+    if (changed) await this.saveAuto()
+  }
+
+  private async ensureAutoLoaded(): Promise<void> {
+    if (this.autoLoaded) return
+
+    try {
+      if (existsSync(this.autoTagsPath)) {
+        const data = await readFile(this.autoTagsPath, 'utf-8')
+        const parsed = JSON.parse(data) as Partial<AutoTagsStore>
+        this.autoTags = parsed.tags ?? {}
+        this.autoProcessed = new Set(parsed.processed ?? [])
+      }
+    } catch {
+      this.autoTags = {}
+      this.autoProcessed = new Set()
+    }
+
+    this.autoLoaded = true
+  }
+
+  private async saveAuto(): Promise<void> {
+    try {
+      const dir = join(this.autoTagsPath, '..')
+      if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true })
+      }
+      const store: AutoTagsStore = {
+        tags: this.autoTags,
+        processed: [...this.autoProcessed],
+      }
+      await writeFile(this.autoTagsPath, JSON.stringify(store, null, 2), 'utf-8')
+    } catch (err) {
+      console.error('Failed to save session auto-tags:', err)
+    }
+  }
+
+  private async ensureLoaded(): Promise<void> {
+    if (this.loaded) return
+
+    try {
+      if (existsSync(this.tagsPath)) {
+        const data = await readFile(this.tagsPath, 'utf-8')
+        this.cache = JSON.parse(data)
+      }
+    } catch {
+      this.cache = {}
+    }
+
+    this.loaded = true
+  }
+
+  private async save(): Promise<void> {
+    try {
+      const dir = join(this.tagsPath, '..')
+      if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true })
+      }
+      await writeFile(this.tagsPath, JSON.stringify(this.cache, null, 2), 'utf-8')
+    } catch (err) {
+      console.error('Failed to save session tags:', err)
+    }
+  }
+}

package/apps/sessrumnir/src/main/session-trash.test.ts

@@ -0,0 +1,66 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { buildTrashArgs, moveToTrash, type TrashSpawn, type TrashSpawnResult } from './session-trash'
+
+/**
+ * A deleted session must land in the desktop trash whenever the machine can
+ * offer one. The regression these cover: trash-cli is absent on most installs,
+ * and when the only helper was `trash`, every delete became a permanent
+ * unlink with no undo.
+ */
+
+const NOT_INSTALLED: TrashSpawnResult = { status: null, error: Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' }) }
+const SUCCEEDED: TrashSpawnResult = { status: 0 }
+const REFUSED: TrashSpawnResult = { status: 1 }
+
+function recordingSpawn(replies: Record<string, TrashSpawnResult>): { spawn: TrashSpawn; calls: Array<{ command: string; args: string[] }> } {
+  const calls: Array<{ command: string; args: string[] }> = []
+  const spawn: TrashSpawn = (command, args) => {
+    calls.push({ command, args })
+    return replies[command] ?? NOT_INSTALLED
+  }
+  return { spawn, calls }
+}
+
+test('trash-cli is used when it is installed, and nothing else is tried', () => {
+  const { spawn, calls } = recordingSpawn({ trash: SUCCEEDED })
+  assert.equal(moveToTrash('/home/u/.pi/agent/sessions/p/a.jsonl', spawn), true)
+  assert.deepEqual(calls.map((c) => c.command), ['trash'])
+})
+
+test('a missing trash-cli falls through to gio instead of failing', () => {
+  // This is the machine the sessions were lost on: no trash-cli, gio present.
+  const { spawn, calls } = recordingSpawn({ trash: NOT_INSTALLED, gio: SUCCEEDED })
+  assert.equal(moveToTrash('/home/u/.omp/agent/sessions/p/a.jsonl', spawn), true)
+  assert.deepEqual(calls.map((c) => c.command), ['trash', 'gio'])
+  assert.deepEqual(calls[1].args, ['trash', '/home/u/.omp/agent/sessions/p/a.jsonl'])
+})
+
+test('no helper installed reports failure so the caller can decide', () => {
+  const { spawn, calls } = recordingSpawn({})
+  assert.equal(moveToTrash('/home/u/.pi/agent/sessions/p/a.jsonl', spawn), false)
+  // Every helper must be attempted before giving up on a recoverable delete.
+  assert.deepEqual(calls.map((c) => c.command), ['trash', 'gio'])
+})
+
+test('a helper that runs and refuses is not treated as success', () => {
+  const { spawn } = recordingSpawn({ trash: REFUSED, gio: REFUSED })
+  assert.equal(moveToTrash('/home/u/.pi/agent/sessions/p/a.jsonl', spawn), false)
+})
+
+test('a refusal by one helper still lets the next one try', () => {
+  const { spawn, calls } = recordingSpawn({ trash: REFUSED, gio: SUCCEEDED })
+  assert.equal(moveToTrash('/home/u/.pi/agent/sessions/p/a.jsonl', spawn), true)
+  assert.deepEqual(calls.map((c) => c.command), ['trash', 'gio'])
+})
+
+test('a path that could read as an option is separated with --', () => {
+  assert.deepEqual(buildTrashArgs([], '-weird.jsonl'), ['--', '-weird.jsonl'])
+  assert.deepEqual(buildTrashArgs(['trash'], '-weird.jsonl'), ['trash', '--', '-weird.jsonl'])
+})
+
+test('an ordinary absolute path is passed without a separator', () => {
+  // Not every minimal `trash` build accepts `--`, so it is added only when needed.
+  assert.deepEqual(buildTrashArgs([], '/home/u/a.jsonl'), ['/home/u/a.jsonl'])
+  assert.deepEqual(buildTrashArgs(['trash'], '/home/u/a.jsonl'), ['trash', '/home/u/a.jsonl'])
+})

package/apps/sessrumnir/src/main/session-trash.ts

@@ -0,0 +1,65 @@
+import { spawnSync } from 'child_process'
+
+/**
+ * Moving a deleted session to the desktop trash instead of destroying it.
+ *
+ * Pi's own session selector shells out to the `trash` CLI, and the GUI
+ * followed it. But `trash` (trash-cli) is a separate package that most
+ * distributions do not install, and the only fallback was `unlink`. On any
+ * machine without trash-cli every confirmed delete was therefore permanent,
+ * with no undo, while the code read as if deletion were recoverable.
+ *
+ * So more than one helper is tried. `gio trash` ships with GLib and is
+ * present on essentially every desktop Linux install, which restores a real
+ * trash bin on the machines trash-cli misses.
+ */
+
+/** Trash helpers in preference order; the first one installed that succeeds wins. */
+const TRASH_HELPERS: ReadonlyArray<{ command: string; leadingArgs: readonly string[] }> = [
+  // trash-cli, matching what Pi itself invokes.
+  { command: 'trash', leadingArgs: [] },
+  // GLib's file mover, part of the `libglib2.0-bin` package every GTK desktop pulls in.
+  { command: 'gio', leadingArgs: ['trash'] },
+]
+
+/** Exit status of a helper that completed successfully. */
+const TRASH_EXIT_OK = 0
+
+export interface TrashSpawnResult {
+  status: number | null
+  /** Set when the helper could not be executed at all, e.g. ENOENT when it is not installed. */
+  error?: Error
+}
+
+export type TrashSpawn = (command: string, args: string[]) => TrashSpawnResult
+
+function runTrashHelper(command: string, args: string[]): TrashSpawnResult {
+  const result = spawnSync(command, args, { encoding: 'utf-8' })
+  return { status: result.status, error: result.error }
+}
+
+/**
+ * Arguments for one helper. `--` is added only for a path that could be read
+ * as an option, because not every minimal `trash` build accepts the separator.
+ */
+export function buildTrashArgs(leadingArgs: readonly string[], targetPath: string): string[] {
+  return targetPath.startsWith('-')
+    ? [...leadingArgs, '--', targetPath]
+    : [...leadingArgs, targetPath]
+}
+
+/**
+ * Try every trash helper in turn. Returns true once one reports success.
+ * A helper that is not installed is skipped, not treated as a refusal to
+ * delete, so a missing trash-cli falls through to `gio` rather than to
+ * permanent removal.
+ */
+export function moveToTrash(targetPath: string, spawn: TrashSpawn = runTrashHelper): boolean {
+  for (const { command, leadingArgs } of TRASH_HELPERS) {
+    const result = spawn(command, buildTrashArgs(leadingArgs, targetPath))
+    // No status at all means the helper never ran (not installed); try the next.
+    if (result.error) continue
+    if (result.status === TRASH_EXIT_OK) return true
+  }
+  return false
+}