pi-hashline-edit-pro 3.0.0 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/src/constants.ts

@@ -6,6 +6,8 @@ export const MAX_OVERSIZED_WARNING_LINES = 100;
 export const MAX_HASH_SOURCE_BYTES = 500;
 export const MAX_GREP_LINE_BYTES = 500;
 
+export const MAX_DIFF_INPUT_BYTES = 1024 * 1024;
+
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 7;
 export const NEW_CONTENT_NOT_ARRAY_MSG =

package/src/edit-common.ts

@@ -16,7 +16,7 @@ export function editRenderResultWrapper(
 }
 
 export function editRenderCallWrapper(
-  preview: (args: unknown, cwd: string) => Promise<RPreview>,
+  preview: (args: unknown, cwd: string, signal?: AbortSignal) => Promise<RPreview>,
   getInput?: (args: unknown) => { path?: string } | null,
   toolName?: string,
 ) {

package/src/fs-write.ts

@@ -100,20 +100,21 @@ export async function resolveTarget(path: string): Promise<string> {
 const TEMP_PREFIX = ".tmp-";
 const TEMP_UUID_RE = /^\.tmp-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const STALE_TEMP_MS = 60 * 60 * 1000;
-const sweptDirs = new Set<string>();
+const sweptDirs = new Map<string, number>();
 
 async function sweepStaleTemps(dir: string): Promise<void> {
-  if (sweptDirs.has(dir)) return;
-  sweptDirs.add(dir);
+  const sweepNow = Date.now();
+  const lastSweep = sweptDirs.get(dir);
+  if (lastSweep !== undefined && sweepNow - lastSweep < STALE_TEMP_MS) return;
+  sweptDirs.set(dir, sweepNow);
   try {
     const entries = await readdir(dir, { withFileTypes: true });
-    const now = Date.now();
     for (const entry of entries) {
       if (!entry.isFile() || !TEMP_UUID_RE.test(entry.name)) continue;
       const tempPath = join(dir, entry.name);
       try {
         const stats = await stat(tempPath);
-        if (now - stats.mtimeMs > STALE_TEMP_MS) {
+        if (sweepNow - stats.mtimeMs > STALE_TEMP_MS) {
           await rm(tempPath, { force: true });
         }
       } catch {

package/src/grep.ts

@@ -274,10 +274,16 @@ function makeHitFromIndices(
   };
 }
 
+let cachedRgPath: string | undefined;
+export function clearRgPathCache(): void {
+  cachedRgPath = undefined;
+}
+
 async function resolveRgPath(): Promise<string> {
+  if (cachedRgPath !== undefined) return cachedRgPath;
   try {
     const r = spawnSync("rg", ["--version"], { stdio: "pipe" });
-    if (!r.error && r.status === 0) return "rg";
+    if (!r.error && r.status === 0) { cachedRgPath = "rg"; return "rg"; }
   } catch {}
   try {
     const { homedir } = await import("os");
@@ -287,7 +293,7 @@ async function resolveRgPath(): Promise<string> {
     const bin = join(base, "bin", process.platform === "win32" ? "rg.exe" : "rg");
     if (existsSync(bin)) {
       const r = spawnSync(bin, ["--version"], { stdio: "pipe" });
-      if (!r.error && r.status === 0) return bin;
+      if (!r.error && r.status === 0) { cachedRgPath = bin; return bin; }
     }
   } catch {}
   try {
@@ -300,7 +306,7 @@ async function resolveRgPath(): Promise<string> {
     const mod = await import("file://" + toolsManagerPath);
     if (mod.ensureTool) {
       const p = await mod.ensureTool("rg", true);
-      if (p) return p;
+      if (p) { cachedRgPath = p; return p; }
     }
   } catch {}
   throw new Error("[E_ACCESS] ripgrep (rg) is required for grep but was not found. Install ripgrep or ensure pi can download it to ~/.pi/agent/bin.");
@@ -366,6 +372,7 @@ async function collectRgMatches(
     });
     child.on("error", (error) => {
       cleanup();
+      if (rgPath === cachedRgPath) cachedRgPath = undefined;
       reject(error);
     });
     child.on("close", (code) => {
@@ -494,17 +501,22 @@ export function regGrep(pi: ExtensionAPI): void {
         const sortedNums = [...allNums].sort((a, b) => a - b);
         const indices = sortedNums.map((n) => n - 1).filter((n) => n >= 0);
         if (countOnly) {
+          if (globRegex) {
+            const displayPath = relative(ctx.cwd, absPath).replace(/\\/g, "/");
+            const globPath = relative(globRoot, absPath).replace(/\\/g, "/");
+            if (!globRegex.test(globPath) && !globRegex.test(displayPath)) continue;
+          }
           const norm = await tryReadNormFile(absPath, ctx.cwd, { maxLines: MAX_HASH_LINES, noPersist: true, signal });
           if (!norm) continue;
           const hit = makeHitFromIndices(norm, relative(ctx.cwd, absPath).replace(/\\/g, "/"), indices, context, validatedRegex, totalForFile, indices.length);
           const display = displayRowsForHit(hit);
           totalRows += display.length;
           for (const r of display) totalBytes += Buffer.byteLength(r, "utf-8") + 1;
-          const remaining = limit - matches;
-          if (remaining > 0) {
-            const add = Math.min(hit.matchCount, remaining);
+          const remainingCountOnly = limit - matches;
+          if (remainingCountOnly > 0) {
+            const add = Math.min(hit.matchCount, remainingCountOnly);
             matches += add;
-            if (hit.matchCount > remaining) limitTruncated = true;
+            if (hit.matchCount > remainingCountOnly) limitTruncated = true;
           } else {
             limitTruncated = true;
           }
@@ -515,13 +527,13 @@ export function regGrep(pi: ExtensionAPI): void {
           limitTruncated = true;
           break;
         }
-        const norm = await tryReadNormFile(absPath, ctx.cwd, { maxLines: MAX_HASH_LINES, noPersist: true, signal });
-        if (!norm) continue;
         if (globRegex) {
           const displayPath = relative(ctx.cwd, absPath).replace(/\\/g, "/");
           const globPath = relative(globRoot, absPath).replace(/\\/g, "/");
           if (!globRegex.test(globPath) && !globRegex.test(displayPath)) continue;
         }
+        const norm = await tryReadNormFile(absPath, ctx.cwd, { maxLines: MAX_HASH_LINES, noPersist: true, signal });
+        if (!norm) continue;
         const hit = makeHitFromIndices(norm, relative(ctx.cwd, absPath).replace(/\\/g, "/"), indices, context, validatedRegex, totalForFile, Math.min(totalForFile, remaining));
         if (!hit) continue;
         const display = displayRowsForHit(hit);

package/src/hash-store.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "crypto";
 import { existsSync } from "fs";
 import { chmod, readFile, rename, mkdir, stat } from "fs/promises";
 import { hashStorePath, hashStoreDir, legacyHashStorePath } from "./paths";
@@ -226,7 +227,7 @@ function isHealthy(db: RawDb): boolean {
 }
 
 async function quarantineStore(storePath: string): Promise<void> {
-  const suffix = `.corrupt-${Date.now()}`;
+  const suffix = `.corrupt-${Date.now()}-${process.pid}-${randomUUID()}`;
   for (const candidate of [storePath, `${storePath}-wal`, `${storePath}-shm`]) {
     try {
       await rename(candidate, `${candidate}${suffix}`);
@@ -442,7 +443,7 @@ export function getSnapshot(
     snapshotCache.set(path, cached);
     return cached.hashes.slice();
   }
-  const row = store.stmts.get(path, checksum, lineCount);
+  const row = withBusyRetry(() => store.stmts.get(path, checksum, lineCount));
   const parsed = parseStoredHashes(row, () => {
     if (deleteCorrupt) store.stmts.deleteOne(path);
     snapshotCache.delete(path);
@@ -484,7 +485,7 @@ export function upsertUndo(store: HashStore, path: string, entry: UndoRecord): v
 }
 
 export function getUndoEntry(store: HashStore, path: string): UndoRecord | undefined {
-  const row = store.stmts.undoGet(path);
+  const row = withBusyRetry(() => store.stmts.undoGet(path));
   if (!row) return undefined;
   const parsed = parseStoredHashes(row, () => store.stmts.undoDelete(path));
   if (!parsed) return undefined;

package/src/hashline/parse.ts

@@ -60,7 +60,13 @@ function unwrapJsonEnvelope(line: string, warnings?: string[]): string {
   if (!match) return line;
   const withoutDot = line.trim().slice(0, -1);
   try {
-    JSON.parse(withoutDot);
+    const parsed: unknown = JSON.parse(withoutDot);
+    if (Array.isArray(parsed) && parsed.length === 1 && typeof parsed[0] === "string") {
+      warnings?.push(
+        '[E_BAD_SHAPE] Unwrapped JSON array syntax from a replacement_lines element.',
+      );
+      return parsed[0];
+    }
     return line;
   } catch {
     warnings?.push(

package/src/insert.ts

@@ -8,7 +8,7 @@ import { MAX_HASH_LINES, parseHashRef, resolveAnchorLine, type Anchor } from "./
 import { stripAnchorRow } from "./hashline/resolve";
 import { loadP, loadGuide } from "./prompts";
 import { normReq } from "./payload-contract";
-import { isRec, rejectUnknownFields, splitLines } from "./utils";
+import { decodeStringArray, isRec, rejectUnknownFields, splitLines } from "./utils";
 import { clearBoundaryBypass } from "./boundary-bypass";
 import type { RPreview, RRState } from "./replace-render";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper } from "./edit-common";
@@ -101,15 +101,20 @@ function buildInsertEdit(
   return { editParams, anchorLine };
 }
 
-export async function insertPreview(request: unknown, cwd: string): Promise<RPreview> {
+export async function insertPreview(request: unknown, cwd: string, signal?: AbortSignal): Promise<RPreview> {
   try {
     const normalized = normReq(request);
+    if (isRec(normalized)) {
+      const expanded = decodeStringArray(normalized.lines);
+      if (expanded) normalized.lines = expanded;
+    }
     assertInsertReq(normalized);
     const { ref } = parseInsertAnchor(normalized.anchor);
     const preload = await readNormFile(normalized.path, cwd, {
       accessMode: constants.R_OK,
       maxLines: MAX_HASH_LINES,
       noPersist: true,
+      signal,
     });
     const { editParams } = buildInsertEdit(normalized, preload, ref);
     const pipe = await execPipeline(editParams, cwd, {
@@ -117,9 +122,11 @@ export async function insertPreview(request: unknown, cwd: string): Promise<RPre
       noPersist: true,
       preloadedNorm: preload,
       skipBoundaryDedup: true,
+      signal,
     });
     return previewFromPipe(pipe);
   } catch (error: unknown) {
+    if (signal?.aborted) throw error;
     return previewError(error);
   }
 }
@@ -163,6 +170,14 @@ export function buildInsertToolDef(): InsertToolDef {
     renderResult: editRenderResultWrapper,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const canonical = normReq(params);
+      const insertWarnings: string[] = [];
+      if (isRec(canonical)) {
+        const expanded = decodeStringArray(canonical.lines);
+        if (expanded) {
+          insertWarnings.push('[E_BAD_SHAPE] Unwrapped JSON array syntax from a lines element.');
+          canonical.lines = expanded;
+        }
+      }
       assertInsertReq(canonical);
       const req = canonical;
       const path = req.path;
@@ -188,7 +203,7 @@ export function buildInsertToolDef(): InsertToolDef {
           verb: "inserted",
           noopNoun: "Insertion",
           foldedAnchorLines: anchorLine === undefined ? 0 : 1,
-          prefixWarnings: anchorWarnings,
+          prefixWarnings: [...anchorWarnings, ...insertWarnings],
           onApplied: () => clearBoundaryBypass(mutationTargetPath),
         });
       });

package/src/replace-diff.ts

@@ -4,7 +4,10 @@ import {
   _lineHashesPure,
   ANCHOR_LEN,
   HASH_SEP,
+  changedRange,
 } from "./hashline";
+import { MAX_DIFF_INPUT_BYTES } from "./constants";
+import { splitLines } from "./utils";
 import {
   detectEnding,
   toLF,
@@ -48,9 +51,63 @@ export function genDiff(
   oldContentHashes?: string[],
   limits?: DiffLimits,
 ): { diff: string; firstChangedLine: number | undefined; lineNumbers: (number|undefined)[] } {
-  const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
   const maxLineBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxLineBytes ?? DEFAULT_MAX_BYTES);
   const maxBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxBytes ?? DEFAULT_MAX_BYTES);
+  if (!limits?.unlimited && Buffer.byteLength(oldContent, "utf-8") + Buffer.byteLength(newContent, "utf-8") > MAX_DIFF_INPUT_BYTES) {
+    const guardedRange = changedRange(oldContent, newContent);
+    const guardNote = `[diff truncated at ${formatSize(maxBytes)}; use read to see the rest.]`;
+    if (!guardedRange || !newContentHashes) {
+      return { diff: ` ...\n${guardNote}`, firstChangedLine: guardedRange?.firstChangedLine, lineNumbers: [undefined, undefined] };
+    }
+    const newLines = splitLines(newContent);
+    const oldLines = splitLines(oldContent);
+    const first = guardedRange.firstChangedLine;
+    const last = guardedRange.lastChangedLine;
+    const suffixLen = newLines.length - last;
+    const oldLast = oldLines.length - suffixLen;
+    const beforeStart = Math.max(1, first - contextLines);
+    const afterEnd = Math.min(newLines.length, last + contextLines);
+    const guarded: string[] = [];
+    const guardedNumbers: (number|undefined)[] = [];
+    let guardedBytes = 0;
+    const pushGuarded = (text: string, num?: number): boolean => {
+      const size = Buffer.byteLength(text, "utf-8") + 1;
+      if (guardedBytes + size > maxBytes) return false;
+      guardedBytes += size;
+      guarded.push(text);
+      guardedNumbers.push(num);
+      return true;
+    };
+    const pushGuardedRow = (prefix: " " | "+" | "-", line: string, hash: string | undefined, num?: number): boolean => {
+      const full = fmtDiffLine(prefix, line, hash);
+      if (Buffer.byteLength(full, "utf-8") > maxLineBytes) {
+        const marker = `[Row is ${formatSize(Buffer.byteLength(full, "utf-8"))}, exceeds ${formatSize(maxLineBytes)}; content not shown. Use read to see the full line.]`;
+        return pushGuarded(fmtDiffLine(prefix, marker, hash), num);
+      }
+      return pushGuarded(full, num);
+    };
+    if (beforeStart > 1) pushGuarded(" ...", undefined);
+    for (let n = beforeStart; n < first; n++) {
+      if (!pushGuardedRow(" ", newLines[n - 1]!, newContentHashes[n - 1], n)) break;
+    }
+    if (oldContent.length > 0) {
+      for (let n = first; n <= Math.min(oldLast, oldLines.length); n++) {
+        if (!pushGuardedRow("-", oldLines[n - 1]!, oldContentHashes?.[n - 1], n)) break;
+      }
+    }
+    for (let n = first; n <= last; n++) {
+      if (!pushGuardedRow("+", newLines[n - 1]!, newContentHashes[n - 1], n)) break;
+    }
+    for (let n = last + 1; n <= afterEnd; n++) {
+      if (!pushGuardedRow(" ", newLines[n - 1]!, newContentHashes[n - 1], n)) break;
+    }
+    guarded.push(" ...");
+    guardedNumbers.push(undefined);
+    guarded.push(guardNote);
+    guardedNumbers.push(undefined);
+    return { diff: guarded.join("\n"), firstChangedLine: first, lineNumbers: guardedNumbers };
+  }
+  const effectiveNewHashes = newContentHashes ?? _lineHashesPure(newContent);
 
   const parts = Diff.diffLines(oldContent, newContent);
   const output: string[] = [];

package/src/replace-render.ts

@@ -19,6 +19,7 @@ export type RRState = {
 	preview?: RPreview;
 	previewGeneration?: number;
 	previewTimer?: ReturnType<typeof setTimeout>;
+	previewAbort?: AbortController;
 };
 
 type DiffRowKind = "added" | "removed" | "context";
@@ -232,7 +233,7 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
 }
 
 export function makeRenderCall(
-	preview: (args: unknown, cwd: string) => Promise<RPreview>,
+	preview: (args: unknown, cwd: string, signal?: AbortSignal) => Promise<RPreview>,
 	options: { getInput?: (args: unknown) => { path?: string } | null; toolName?: string } = {},
 ) {
 	const getInput = options.getInput ?? getPreviewInput;
@@ -244,6 +245,10 @@ export function makeRenderCall(
 				clearTimeout(context.state.previewTimer);
 				context.state.previewTimer = undefined;
 			}
+			if (context.state.previewAbort) {
+				context.state.previewAbort.abort();
+				context.state.previewAbort = undefined;
+			}
 		};
 		if (context.executionStarted) {
 			cancelPendingPreview();
@@ -265,8 +270,12 @@ export function makeRenderCall(
 				context.state.previewGeneration = previewGeneration;
 				context.state.previewTimer = setTimeout(() => {
 					context.state.previewTimer = undefined;
-					preview(args, context.cwd)
+					const controller = new AbortController();
+					context.state.previewAbort = controller;
+					preview(args, context.cwd, controller.signal)
 						.then((result) => {
+							if (controller.signal.aborted) return;
+							if (context.state.previewAbort === controller) context.state.previewAbort = undefined;
 							if (
 								context.state.argsKey === argsKey &&
 								context.state.previewGeneration === previewGeneration
@@ -276,6 +285,8 @@ export function makeRenderCall(
 							}
 						})
 						.catch((err: unknown) => {
+							if (controller.signal.aborted) return;
+							if (context.state.previewAbort === controller) context.state.previewAbort = undefined;
 							if (
 								context.state.argsKey === argsKey &&
 								context.state.previewGeneration === previewGeneration
@@ -311,6 +322,10 @@ export function renderEditResult(
 			clearTimeout(renderState.previewTimer);
 			renderState.previewTimer = undefined;
 		}
+		if (renderState.previewAbort) {
+			renderState.previewAbort.abort();
+			renderState.previewAbort = undefined;
+		}
 		renderState.preview = undefined;
 		renderState.previewGeneration = (renderState.previewGeneration ?? 0) + 1;
 	}

package/src/replace-undo.ts

@@ -105,6 +105,9 @@ export function regUndo(pi: ExtensionAPI): void {
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const path = params.path;
+      if (typeof path !== "string" || path.length === 0) {
+        throw new Error('[E_BAD_SHAPE] Undo request requires a non-empty "path" string.');
+      }
       const { resolved: mutationTargetPath } = await resolveInCwd(path, ctx.cwd);
 
       const undo = await getUndo(mutationTargetPath);

package/src/replace.ts

@@ -9,7 +9,7 @@ import {
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
 import { editToolSchema, type ReqParams, assertReq, normReq } from "./payload-contract";
-import { isRec } from "./utils";
+import { decodeStringArray, isRec } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { type FileIdentity } from "./fs-write";
 import { applyEdit,
@@ -160,11 +160,17 @@ export async function execPipeline(
   const path = params.path;
 
   const editWarnings: string[] = [];
+  let replacementLines = params.replacement_lines;
+  const expandedReplacement = decodeStringArray(replacementLines);
+  if (expandedReplacement) {
+    editWarnings.push('[E_BAD_SHAPE] Unwrapped JSON array syntax from a replacement_lines element.');
+    replacementLines = expandedReplacement;
+  }
   const edit = resEdit(
     {
       remove_from: params.remove_from,
       remove_to: params.remove_to,
-      replacement_lines: params.replacement_lines,
+      replacement_lines: replacementLines,
     },
     editWarnings,
   );
@@ -246,6 +252,7 @@ export function previewError(error: unknown): RPreview {
 export async function compPreview(
   request: unknown,
   cwd: string,
+  signal?: AbortSignal,
 ): Promise<RPreview> {
   try {
     const normalized = normReq(request);
@@ -253,10 +260,11 @@ export async function compPreview(
     const pipe = await execPipeline(
       normalized,
       cwd,
-      { accessMode: constants.R_OK, noPersist: true },
+      { accessMode: constants.R_OK, noPersist: true, signal },
     );
     return previewFromPipe(pipe);
   } catch (error: unknown) {
+    if (signal?.aborted) throw error;
     return previewError(error);
   }
 }

package/src/served.ts

@@ -1,4 +1,5 @@
 import { loadHashStore, parseStoredServed, STORE_NOT_OPEN_MESSAGE, withStore, type HashStore } from "./hash-store";
+import { withBusyRetry } from "./hash-store/retry";
 import { HASH_CLASS } from "./hashline/alphabet";
 import { contentChecksum } from "./hashline/hasher";
 
@@ -37,7 +38,7 @@ export function buildServedMap(fileHashes: string[], fileLines: string[], wanted
 }
 
 export function getServed(store: HashStore, path: string): Map<string, string> | undefined {
-  const row = store.stmts.servedGet(path);
+  const row = withBusyRetry(() => store.stmts.servedGet(path));
   const parsed = parseStoredServed(row, () => store.stmts.servedDelete(path));
   if (!parsed) return undefined;
   return parsed;

package/src/utils.ts

@@ -168,3 +168,84 @@ function formatLineLimit(displayPath: string, limit: number, count: number | und
 	const detail = count === undefined ? `has more than ${limit}` : `has ${count}`;
 	return `[E_FILE_TOO_LARGE] ${displayPath} ${detail} lines, exceeding the ${limit}-line hashline limit. For very large files, use write.`;
 }
+
+function escapeRawControl(value: string): string {
+	if (value === "\b") return "\\b";
+	if (value === "\t") return "\\t";
+	if (value === "\n") return "\\n";
+	if (value === "\f") return "\\f";
+	if (value === "\r") return "\\r";
+	const hex = value.charCodeAt(0).toString(16).padStart(4, "0");
+	return `\\u${hex}`;
+}
+
+function escapeControls(value: string): string {
+	let out = "";
+	for (const char of value) {
+		out += char.charCodeAt(0) < 32 ? escapeRawControl(char) : char;
+	}
+	return out;
+}
+
+function decodeArraySegment(segment: string): string | undefined {
+	const trimmed = segment.trim();
+	if (trimmed.length < 2 || !trimmed.startsWith('"') || !trimmed.endsWith('"')) return undefined;
+	try {
+		const cleaned = escapeControls(trimmed);
+		const parsed: unknown = JSON.parse(cleaned);
+		return typeof parsed === "string" ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function splitArraySegments(inner: string): string[] | undefined {
+	const segments: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	let escaped = false;
+	for (const char of inner) {
+		if (inQuotes) {
+			current += char;
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === '"') inQuotes = false;
+			continue;
+		}
+		if (char === '"') {
+			inQuotes = true;
+			current += char;
+			continue;
+		}
+		if (char === ",") {
+			segments.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	if (inQuotes || escaped) return undefined;
+	segments.push(current);
+	return segments;
+}
+
+function decodeArrayText(value: unknown): string[] | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return undefined;
+	const segments = splitArraySegments(trimmed.slice(1, -1));
+	if (!segments) return undefined;
+	const decoded: string[] = [];
+	for (const segment of segments) {
+		const part = decodeArraySegment(segment);
+		if (part === undefined) return undefined;
+		decoded.push(part);
+	}
+	return decoded.length > 0 ? decoded : undefined;
+}
+
+export function decodeStringArray(value: unknown): string[] | undefined {
+	if (typeof value === "string") return decodeArrayText(value);
+	if (Array.isArray(value) && value.length === 1) return decodeArrayText(value[0]);
+	return undefined;
+}