sessions

func AcquireResumeLock ¶

func AcquireResumeLock(sessionPath, id string) (release func(), err error)

AcquireResumeLock takes the exclusive per-session advisory lock required on resume before the updated_at refresh. It locks the session file's dedicated sidecar — ResumeLockPath(sessionPath) — for up to two seconds via the same kernel mechanism as; id names the session for the failure line only. On success it returns a non-nil release and a nil error: the caller holds release for the lifetime of the run and calls it on exit (the kernel also releases the lock if the process dies, so no per-turn re-lock is needed). A contended lock returns a *ResumeLockError with ReasonLockTimeout; any other lock-syscall failure returns one with ReasonLockAcquireError and the observed error category. Per-turn session writes (Store.Flush) never re-acquire this lock, so lock_timeout / lock_acquire_error cannot surface on a session_write_failed event.

func CanonicalizeFolder ¶

func CanonicalizeFolder(path string) (string, error)

CanonicalizeFolder resolves path to the canonical absolute folder path used by metadata.folder, <folder-dir> hashing, and resume CWD checks. It makes the path absolute, resolves symlinks, and removes trailing slashes and "."/".." segments. The path must exist, since symlink resolution reads it.

func DeleteSession ¶

func DeleteSession(path string) (fserrors.Category, error)

DeleteSession removes the session file at path and its dedicated sidecar lock behind the same non-blocking sidecar lock the retention pruner uses, so an explicit delete and a concurrent prune or resume cannot drift on lock or sidecar handling. It is the persistence behind the /resume picker's delete action.

It returns the error category and a non-nil error on failure, or ("", nil) on success. A lock already held by another codemeld instance (the session is being resumed elsewhere) is refused with fserrors.InUse and the file is left intact; any other lock-acquire failure returns its categorized error; a session-file unlink failure returns the unlink's category.

func EnsureFolderDir ¶

func EnsureFolderDir(home, canonicalFolder string) (subdirPath string, err error)

EnsureFolderDir creates ~/.codemeld/sessions and the per-folder subdirectory for canonicalFolder, then ensures the subdirectory's folder file records that canonical path. It returns the per-folder subdirectory path. The call is idempotent: when the folder file already records canonicalFolder it is left untouched. A folder file recording a different folder yields a *CollisionError; filesystem failures yield a *FolderDirError carrying the operation token, path, and category for the runner to render. It never prints or exits.

func FolderDirName ¶

func FolderDirName(canonicalFolder string) string

FolderDirName returns the per-folder directory name <hash>-<basename> for a canonical folder path. <hash> is the first 16 bytes of the SHA-256 of the path, lowercase hex (32 chars); <basename> is the final path component with bytes outside [A-Za-z0-9_.-] replaced by "_" and capped at 32 characters, or "root" for the filesystem root.

func ListResumable ¶

func ListResumable(home, cwd string) ([]ListEntry, []SkippedID, error)

ListResumable lists the resumable sessions in the per-folder subdirectory for the current canonical folder. It returns the survivors, the ids it skipped, and a typed enumeration error — it prints nothing and leaves the tty gate, skipped-id output, and listing to the caller (RunResumeListPreflight and later CLI/TUI orchestration).

The subdirectory is SessionRoot(home)/<folder-dir> for CanonicalizeFolder(cwd); it is never created here, because a missing subdirectory must read as a clean empty listing. An absent subdirectory yields an empty result and a nil error; any other readdir failure yields a *ResumeListEnumerateError.

Each non-directory <id>.json file is read in bounded slices instead of loaded whole: its metadata line, a forward budget ending at the first user message, and a tail window. Record-stream and event-payload validation deliberately do not run here — a session that fails them is listed and rejected at selection by ResolveResumeID, which can report the error against a named session. A candidate joins the skipped bucket, without surfacing its reason, only when its metadata line cannot be read or parsed, is refused on schema_version grounds, or names a folder the folder file does not match. Survivors are sorted by the later of metadata.updated_at and the newest record timestamp in the tail window, descending, ties broken by id (file stem) descending.

func ListResumableAll ¶

func ListResumableAll(home string) ([]ListEntry, []ListAllSkip, error)

func Marshal ¶

func Marshal(s *Session) ([]byte, error)

Marshal serializes a Session to its canonical JSONL byte form: the first line is a tagged metadata record, followed by one message/event record per line. Lines are compact JSON with stable field order and canonical UTC millisecond timestamps.

func OpenSession ¶

func OpenSession(path string) (*Session, VersionStatus, error)

OpenSession reads the JSONL session file at path, pre-scans metadata.schema_version from the first line before any full parse, and classifies it. It refuses a newer or unparseable version with a *VersionError, without parsing records — a future breaking schema may carry fields the current record parser cannot understand, so refusal must not depend on a successful full Unmarshal. For an equal or older-fork-eligible version it delegates to Unmarshal and returns the parsed session with its status, so callers load equal files normally and present the read-only + fork UI for older files.

A read failure or a genuine JSONL parse failure is returned as an ordinary error with an empty status, distinct from a version refusal; callers surface those via the "cannot be parsed" path.

func ResumeLockPath ¶

func ResumeLockPath(sessionPath string) string

ResumeLockPath returns the dedicated sidecar lock-file path (<session-file>.lock) for sessionPath. The --resume advisory lock and the retention pruner's non-blocking pre-unlink lock MUST both derive their target through this one helper: the lock cannot bind to the session file itself because per-turn writes and the updated_at refresh replace that inode via atomic temp+rename, which would orphan the lock and break cross-instance mutual exclusion.

func RunResumeListPreflight ¶

func RunResumeListPreflight(stdin io.Reader, stdinFd int, stderr io.Writer, stderrFd int, skipped []SkippedID, isTerminal func(fd int) bool, waitKey func(stdin io.Reader, stdinFd int)) (exitCode int)

func SessionRoot ¶

func SessionRoot(home string) string

SessionRoot returns the sessions root directory ~/.codemeld/sessions for the given home directory.

func SetTitle ¶

func SetTitle(path, title string) (fserrors.Category, error)

SetTitle sets the optional metadata.title on the session file at path and rewrites the file atomically. It is the persistence behind the /resume picker's rename action an additive metadata field whose non-empty value overrides the auto-derived row preview. It returns the error category and a non-nil error on failure, or ("", nil) on success.

It takes one non-blocking attempt on the session's dedicated sidecar lock — the same target a live resume, an explicit delete, and the retention pruner use (ResumeLockPath) — so a rename can never race a resumed session's whole-file flush, another rename, or a delete/prune unlink. A lock held by another codemeld instance is refused with fserrors.InUse and the file is left unchanged; any other lock-acquire failure returns its categorized error.

func StartBackgroundPrune ¶

func StartBackgroundPrune(home string, retentionDays int, appendSummary func(PruneResult))

StartBackgroundPrune runs Prune in a goroutine and invokes appendSummary with the completed result, so a fresh launch prunes opportunistically without blocking startup (background mode; the only prune path). appendSummary is the caller's seam for resolving the active session at append time and appending session_prune_summary only when a session is active; when no session is active the callback drops the result silently. The callback indirection keeps the event conversion and append in the caller, since internal/sessions must not import internal/events.

func ValidateEventPayloads ¶

func ValidateEventPayloads(records []Record, validate PayloadValidator) error

ValidateEventPayloads runs validate over every Event record's per-kind payload, returning the first failure located by record index as records[<N>].payload: <detail>. It is the load-path composition point for the per-kind event validation beside ValidateRecordStream's spine checks; message records carry no event payload and are skipped. A nil validate is a no-op, so a caller that has not wired a payload validator runs the rest of the load path unchanged.

func ValidateRecordStream ¶

func ValidateRecordStream(records []Record) error

ValidateRecordStream enforces the load-time rules over an already-parsed record slice (as returned by Unmarshal): cross-record tool-call correlation between assistant tool_calls entries and the tool messages that answer them, the sibling-field placement restrictions (tool_call_id only on tool messages, tool_calls only on assistant messages), and the launch_began payload.source enum. It is the validator surface later load/resume orchestration composes with OpenSession and the per-kind event payload validation in internal/events; it does not wire those callers itself.

Errors locate the offending record by its zero-based index in the slice using the form records[<N>] and use the exact wording.

Validation runs in two passes so a malformed tool record receives its own required error rather than being masked by its assistant's completeness check. The first pass validates, in record order, per-record facts: sibling-field placement, each tool message's missing/empty/predecessor/mismatch checks, and launch_began payloads. Only after every tool record has passed its own checks does the second pass validate assistant tool-call type and response-group completeness. Within each pass the first violation in record order is returned.